23.12 Angular Packages and creation

Info

This article is mostly about the creation of angular packages.

Most of this information is copied n formatted from the the angular v18 docs, except for the npm publishing stuff.

List of packages

This is a list of packages that I have used in the past.

• 23.11 NGX-CHARTS for displaying charts.
• angular material has a lot of shit. (in a good way)
• as split is a movable / draggable divider.

Your own angular package

Creating an package

According to the angular v18 docs, Use the following commands:

Naming your library

You should be very careful when choosing the name of your library if you want to publish it later in a public package registry such as npm. See Publishing your library.

Avoid using a name that is prefixed with ng-, such as ng-library. The ng- prefix is a reserved keyword used from the Angular framework and its libraries. The ngx- prefix is preferred as a convention used to denote that the library is suitable for use with Angular. It is also an excellent indication to consumers of the registry to differentiate between libraries of different JavaScript frameworks.

ng new <your-workspace-name> --no-create-application
cd <your-workspace-name>
ng generate library <your-library-name>

Important

If you want to use the package without publishing it to npm, you have to create an empty workspace, and add your applications to it. that’s why we put --no-create-application in the workspace creation line.

Now you can just add files in the lib folder like you would normally.

Adding components

Run ng generate component component-name --project <your-library-name> to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module --project <your-library-name>.

Warning

Note: Don’t forget to add --project <your-library-name> or else it will be added to the default project in your angular.json file.

Assets

In your Angular library, the distributable can include additional assets like theming files, Sass mixins, or documentation (like a changelog). For more information copy assets into your library as part of the build and embed assets in component styles.

ng-packagr will merge handwritten "exports" with the auto-generated ones, allowing for library authors to configure additional export subpaths, or custom conditions.

"exports": {  
	".": {
	    "sass": "./_index.scss",
  },
  "./theming": {    
	  	"sass": "./_theming.scss"  
	},  
	"./prebuilt-themes/indigo-pink.css": {    
		"style": "./prebuilt-themes/indigo-pink.css"  
	}
}

The above is an extract from the @angular/material distributable.

dependencies

Warning

Angular libraries should list any @angular/* dependencies the library depends on as peer dependencies. This ensures that when modules ask for Angular, they all get the exact same module. If a library lists @angular/core in dependencies instead of peerDependencies, it might get a different Angular module instead, which would cause your application to break.

Using your package (building)

Adding an angular app to an already existing workspace.

Make sure the Angular CLI is installed.

Go into the workspace: cd <your-workspace-name>

Create a new application with ng generate application <your-new-app-name>, or ng generate application <your-new-app-name> --minimal --no-standalone

To run it: cd projects/<your-new-app-name>;ng serve --port <random-unused-port-number> (; merges 2 commands into 1 line)

You don’t have to publish your library to the npm package manager to use it in the same workspace, but you do have to build it first.

To use your own library in an application:

• Build the library. You cannot use a library before it is built.

ng build <your-library-name>

Warning

When you use the package locally in the same workspace, and update it with the build command. If you do that whilst the app that is using it is still running (on ng serve), it will crash. So you have to manually stop the app and rerun ng serve or npm run start

• In your applications, import from the library by name:

import { myExport } from '<your-library-name>';

• To use a component, Don’t forget to put it inside the @NgModule({imports: []}). Either in app.module.ts or in the standalone component.

Example

projects/oldmartijntjes-angular-test-lib/src/lib/oldmartijntjes-angular-test-lib.component.ts:

import { Component } from '@angular/core';
 
@Component({
 selector: 'lib-oldmartijntjes-angular-test-lib',
 standalone: true,
 imports: [],
 template: '<p>oldmartijntjes-angular-test-lib works!</p>',
 styles: ''
})
export class OldmartijntjesAngularTestLibComponent {
 
}

projects/appname/src/app/app.module.ts:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { OldmartijntjesAngularTestLibComponent } from 'oldmartijntjes-angular-test-lib';
 
import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';
 
@NgModule({
   declarations: [
       AppComponent
   ],
   imports: [
       BrowserModule,
       AppRoutingModule,
       OldmartijntjesAngularTestLibComponent
   ],
   providers: [],
   bootstrap: [AppComponent]
})
export class AppModule { }

projects/appname/src/app/app.component:

import { Component } from '@angular/core';
 
@Component({
   selector: 'app-root',
   template: '<h1>Welcome to {{title}}!</h1><lib-oldmartijntjes-angular-test-lib></lib-oldmartijntjes-angular-test-lib><router-outlet />',
   styles: []
})
export class AppComponent {
   title = 'testing-angular-app';
}

Gave the following result:

haven’t published your library as an npm package and then installed the package back into your application from npm. For instance, if you clone your git repository and run npm install, your editor shows the <your-library-name> imports as missing if you haven’t yet built your library.

HELPFUL 

When you import something from a library in an Angular application, Angular looks for a mapping between the library name and a location on disk. When you install a library package, the mapping is in the node_modules folder. When you build your own library, it has to find the mapping in your tsconfig paths.

Generating a library with the Angular CLI automatically adds its path to the tsconfig file. The Angular CLI uses the tsconfig paths to tell the build system where to find the library.

For more information, see Path mapping overview.

Important:

The CLI build command uses a different builder and invokes a different build tool for libraries than it does for applications.

• The build system for applications, @angular-devkit/build-angular, is based on webpack, and is included in all new Angular CLI projects
• The build system for libraries is based on ng-packagr. It is only added to your dependencies when you add a library using ng generate library my-lib.

The two build systems support different things, and even where they support the same things, they do those things differently. This means that the TypeScript source can result in different JavaScript code in a built library than it would in a built application.

For this reason, an application that depends on a library should only use TypeScript path mappings that point to the built library. TypeScript path mappings should not point to the library source .ts files.

Publishing

distribution formats

There are two distribution formats to use when publishing a library:

Distribution formats	Details
Partial-Ivy (recommended)	Contains portable code that can be consumed by Ivy applications built with any version of Angular from v12 onwards.
Full-Ivy	Contains private Angular Ivy instructions, which are not guaranteed to work across different versions of Angular. This format requires that the library and application are built with the exact same version of Angular. This format is useful for environments where all library and application code is built directly from source.

npm usage

For publishing to npm use the partial-Ivy format as it is stable between patch versions of Angular.

Avoid compiling libraries with full-Ivy code if you are publishing to npm because the generated Ivy instructions are not part of Angular’s public API, and so might change between patch versions.

Ensuring library version compatibility

The Angular version used to build an application should always be the same or greater than the Angular versions used to build any of its dependent libraries. For example, if you had a library using Angular version 13, the application that depends on that library should use Angular version 13 or later. Angular does not support using an earlier version for the application.

If you intend to publish your library to npm, compile with partial-Ivy code by setting "compilationMode": "partial" in tsconfig.prod.json. This partial format is stable between different versions of Angular, so is safe to publish to npm. Code with this format is processed during the application build using the same version of the Angular compiler, ensuring that the application and all of its libraries use a single version of Angular.

Avoid compiling libraries with full-Ivy code if you are publishing to npm because the generated Ivy instructions are not part of Angular’s public API, and so might change between patch versions.

Link to articles for Ensuring library version compatibility

If you’ve never published a package in npm before, you must create a user account. Read more in Publishing npm Packages. (or in the next header)

publish to npm

To publish on npm, you have to make an npm account here.

The following 3 commands will publish your package to npm. (you only need to login once)

npm login
cd projects/<your-package-folder>
npm publish --access=public

publish to npm on github release

.gitignore

Make sure that your package dist folder isn’t excluded in your .gitignore or .npmingore:

/dist/*
!/dist/[your-package-name]/

replace [your-package-name] with the real name.

Package.json

Make sure that in package.json, in the package folder, private is set to false: "private": false,

This package.json also most have the build script:

"scripts": {
       "build": "ng build",
   },

It is also very important to change the version, because you can’t upload the same package version to npm

Publish.yml We are first going to make github recognise our package with a publish.yml.

add .github/workflows/publish.yml with the following content. Don’t forget to change <your-package-name> to your package name:

name: Publish Library
 
on:
  release:
    types: [published]
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org/'
 
      - name: Install dependencies
        run: npm install
 
      - run: npm ci
 
      - name: Update package.json version
        run: |
          TAG_VERSION=$(echo "${GITHUB_REF}" | sed -n 's/refs\/tags\/v\(.*\)/\1/p')
          echo "Tag version: $TAG_VERSION"
          cd projects/<your-package-name>
          npm --no-git-tag-version version "$TAG_VERSION"
          echo "Updated package.json version to $TAG_VERSION"
 
      - name: Build Angular library
        run: |
          cd projects/<your-package-name>
          npm run build <your-package-name>
 
      - name: Publish package to GitHub Packages
        run: |
          cd projects/<your-package-name>
          npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

NPM access token

We need to give github an access token, so we are going to generate one first.

To generate a token go to: https://www.npmjs.com/settings/<your-npm-username>/tokens and click on add new token.

token types

• Classic NPM Token: This one has less options.
• Granular Access Token: This type of token allows you to specify more fine-grained permissions. Expiration date, which packages it can touch, etc.

Recommendation: For simplicity and if your workflow only involves publishing packages to npm, a classic npm token with sufficient permissions (write or publish) is often sufficient and straightforward to use.

Now that we have our token, we are going to provide it to github.

1. Go to your github repo.
2. Settings
3. Secrets and variables
4. Actions
5. Click on New repository secret.
6. Name it NPM_TOKEN and set the value to the npm token we generated.

Creating a release

Our publish.yml is now setup to publish our package to npm whenever we make a github release. And it automatically converts the version number in the package.json to the tag version of your github release

Adding it locally to already existing repo

In this repo that I am trying to add it to, it’s a repo where you have generated a normal angular app without thinking beforehand that you are going to need a package later.

Info

I am talking about, adding the code / development to an existing repo, not importing it.

So for example, create yourself an angular project:

ng new angular-project-name --no-standalone

steps

1. Create a new workspace structure: First, create a new projects directory in your root folder and move your existing project into it.

mkdir projects
mv src projects/<angular-project-name>
mv .editorconfig projects/<angular-project-name>/
mv tsconfig.app.json projects/<angular-project-name>/
mv tsconfig.spec.json projects/<angular-project-name>/

don’t forget to rename <angular-project-name> to your project name.

Your wokrspace structure should look like this:

|-.vscode/
|-node_modules/
|-projects/
|  |-angular-project-name/
|     |-src/
|     |-.editorconfig
|     |-tsconfig.app.json
|     |-tsconfig.spec.json
|-angular.json
|-package.json
|-package-lock.json
|-tsconfig.json

2. Update angular.json

Update tha paths in the angular.json, for example:

"projects": {
	"<angular-project-name>": {
		"root": "",
		"sourceRoot": "src",
		"architect": {
			"build": {
				"options": {
					"index": "src/index.html",
					"browser": "src/main.ts",
					"tsConfig": "tsconfig.app.json",
					"assets": [
						"src/favicon.ico",
						"src/assets"
					],
					"styles": [
						"@angular/material/prebuilt-themes/purple-green.css",
						"src/styles.scss"
					],
				// ... continue

turns into:

"projects": {
	"<angular-project-name>": {
		"root": "projects/oldmartijntjes-angular-test-lib",
		"sourceRoot": "projects/testing-angular-app/src",
		"architect": {
			"build": {
				"options": {
					"index": "projects/<angular-project-name>/src/index.html",
					"browser": "projects/<angular-project-name>/src/main.ts",
					"tsConfig": "projects/<angular-project-name>/tsconfig.app.json",
					"assets": [
						"projects/<angular-project-name>/src/favicon.ico",
						"projects/<angular-project-name>/src/assets"
					],
					"styles": [
						"@angular/material/prebuilt-themes/purple-green.css",
						"projects/<angular-project-name>/src/styles.scss"
					],
				// ... continue

3. Change tsconfig.app.json and tsconfig.spec.json

change in both files the following:

"extends": "./tsconfig.json", // old
"extends": "../../tsconfig.json", // new

4. Add the package.

TIP

If you have trouble moving your package into the repo, generate a new one to see how it is supposed to look like.

Now there are 2 options, either generate a new one, or copy paste the old package. If you copy paste the package folder, you gotta do the same as you just did for the angular app.

First package

If it is the first package you are importing, and you are doing it by hand, you are going to need package ng-packagr. The path to it is defined in your ng-package.json, make sure it’s correct.

Defining path

When manually copying your package, make sure to add the path to your tsconfig.json, otherwise your apps will not find your package:

"compilerOptions": {
  "paths": {
           "oldmartijntjes-angular-test-lib": [
                "./dist/oldmartijntjes-angular-test-lib"
            ],