What it does

These days, setting up build chains for frontend projects requires lots of knowledge and time. When working with Angular, in particular, there is a fair amount of things to do in order to get an Angular library published just right.

The Angular Package Builder is here to help! Once set up, this NodeJS-based command line tool will build your Angular libraries with a single command, allowing developers to focus on the important things - developing!

Features include:

- :pushpin: Support for primary and (multiple) secondary entry points
- :gift: Support for multiple libraries (e.g. in a monorepo)
- :page_facing_up: Inlining of external resources, such as templates (HTML) and styles (CSS, SASS)
- :hammer: Custom configurations (Angular compiler options, TypeScipt compiler options, external dependencies)

The result is a package, following the official Angular Package Format:

- :green_book: JavaScript build (ES2015, ES5)
- :orange_book: JavaScript bundles (flat ES2015, flat ES5, UMD)
- :blue_book: TypeScript type definition files
- :closed_book: Angular AoT metadata file
- :notebook_with_decorative_cover: package.json file with references to entry files

!Angular Package Builder Preview

How to install

You can get the angular-package-builder via npm by adding it as a new devDependency to your package.json file and running
npm install. Alternatively, run the following command:

`` bash
npm install angular-package-builder --save-dev
`

$3

The following lists the Angular versions supported by the Angular Package Builder. The table also mentions the TypeScript and RxJS
versions which are officially supported by each Angular version. Diverging from this matrix is surely possible yet might lead to
unexpected issues. The last column defines the minimal required NodeJS version.

| Angular | TypeScript | RxJS | NodeJS |
| --------------------------------------- | ----------------------- | ----- | ---------- |
| 4.0.x 4.1.x 4.2.x 4.3.x 4.4.x | 2.1.x 2.2.x 2.3.x | 5.x | >= 7.6.0 |
| 5.0.x | 2.4.x | 5.x | >= 7.6.0 |
| 5.1.x | 2.4.x 2.5.x | 5.x | >= 7.6.0 |
| 5.2.x | 2.4.x 2.5.x 2.6.x | 5.x | >= 7.6.0 |
| 6.0.x | 2.7.x | 6.x | >= 8.0.0 |

> Angular 2 is not supported. Angular versions newer than 6.0.x might work, yet have not not been tested.

How to use

In most cases, integrating angular-package-builder into a project is very straightforward.

> The Angular Package Builder only builds libraries from an Angular / JavaScript perspective. It's possible that you might have to setup
> a few extra build steps, for instance in order to compile global SASS, or copy assets / other files.

$3

Now, every library requires a .angular-package.json file to be present, placed directly next to the package.json file of that library.
Within that .angular-package.json file, you can place the build onfiguration for your library.

A minimal configuration looks like the following:

` json
{
"$schema": "./node_modules/angular-package-builder/angular-package.schema.json",
"entryFile": "./index.ts",
"outDir": "./dist"
}
`

The two options seen above are also the only required ones:

- entryFile is the relative path to the primary entry file
- Usually, entry files are named index.ts
- All further files of the library must be within the same folder, or some place deeper in the directory
- outDir is the relative path to the build output folder
- Usually, the build output folder is named dist
- Don't forget to add the outDir path to your .gitignore file

#### Directory structure

The following directory structure is recommended:

` typescript
── dist/ // Output
└── ...
── src/ // Source
└── ...
── .angular-package.json // Build config
── index.ts // Entry file
── package.json // Package
`

> Note: The build process will create additional files at the root level (where the entry files is placed). Thus, it's highly recommended
> to place all other files in a subfolder - usually that's the src folder.

#### Secondary entry points

Angular, for instance, has packages with multiple entry points: @angular/core as the primary, and @angular/core/testing as the (here
only) secondary. Within the .angular-package.json file, you can define any number of secondary entry points using the secondaryEntries
option. For instance:

` json
{
"$schema": "./node_modules/angular-package-builder/angular-package.schema.json",
"entryFile": "./index.ts",
"outDir": "./dist",
"secondaryEntries": [
{
"entryFile": "./testing/index.ts"
}
]
}
`

$3

Now, run angular-package-builder within one of your package.json scripts. The command accepts an unordered list of paths to
.angular-package.json files as parameters. For instance:

` json
{
"scripts": {
"build": "angular-package-builder ./my-library/.angular-package.json"
}
}
`

#### Multiple libraries

Angular, again, consists of multiple packages, all united in a single Git repository (called monorepo). The Angular Package Builder is
able to build multiple libraries using a single command. Building more libraries means adding more .angular-package.json files to the
corresponding npm script. For example:

` json
{
"scripts": {
"build": "angular-package-builder ./lib-one/.angular-package.json ./lib-two/.angular-package.json"
}
}
`

> The order of the parameters does not matter as the Angular Package Builder will derive the build order independently.

Advanced configuration

Usually, configuring the entryFile and outDir should be sufficient for most libraries. For more advanced use cases or requirements, you
can extend the build configuration in your .angular-package.json file(s).

$3

One of the things you might want to configure specifically for your project is TypeScript. Popular options include strictNullChecks,
skipLibCheck and allowSyntheticDefaultImports. For instance:

` json
{
"typescriptCompilerOptions": {
"strictNullChecks": true
}
}
`

See the TypeScript Compiler Options Documentation for the full
list of available options.

> The following options cannot be changed:

> declaration, emitDecoratorMetadata, experimentalDecorators, module, moduleResolution, newLine, outDir, rootDir,
> sourceRoot and target

$3

Furthermore, you might also decide to configure the Angular compiler differently. Common options are annotateForClosureCompiler,
preserveWhitespaces and strictMetadataEmit. For instance:

` json
{
"angularCompilerOptions": {
"annotateForClosureCompiler": false
}
}
`

> The following options cannot be changed:

> flatModuleId, flatModuleOutFile and skipTemplateCodegen

$3

By default, the Angular Package Builder will identify your libraries' dependencies automatically. If, for some reason, a dependency is
missing or you want to overwrite a dependency definition, you can declare them in the form of package -> global constant. For instance:

` json
{
"dependencies": {
"@ngx-translate/core": "ngxTranslate.core"
}
}
`

Known pitfalls with solutions

There are quite a few pitfalls when packaging an Angular library. Most of them are all but obvious, and the fix is not always clear. The
following is a collection of known pitfally, plus tips on how to solve them.

> Feel free to extend this list by creating an issue!

$3

Usually, libraries are built in a way that allows us to import them from a single source (normally the module name). This is achieved by
re-exporting the implementation (spread accross multiple files) with a so-called
Barrel (normally index.ts).

Now, issues might occur when - somewhere within the library - two barrels meet each other. Funnily enough, should such a constellation
lead to any issues, it won't be appearant right away: Chances are good that the Angular Package Builder will succeed, and the
compilation output might also look correct. At the latest, when trying to import the library into an Angular application, an error will be
thrown (something like "injected dependencies cannot be resolved").

#### Solution

We recommend to only use a single barrel / index.ts file at the root of you library, re-exporting all public functionality from that
single place.

$3

The usage of type-related JSDoc tags / information within JSdoc tags is disallowed, reason being that the TypeScript syntax already exposes
this kind of information. Forbidden are (amongst other things):

- type information in parameter tags (e.g. @param {string} myOption)
- type-related tags on variables, functions, classes (e.g. @type, @constructor, @function, @class)
- tags regarding visibility (e.g. @private, @public)
- further redundant tags such as @static, @extends, @implements

> The full list of allowed / disallowed JSDoc tags can be found
in the tsickle source.

If any of those tags are being used anyway, the Angular Compiler (tsickle to be specific) will complain:

!Angular Package Builder - forbidden JSdoc error

#### Solution

Preferably, remove all redundant JSDoc tags until the Angular Compiler is happy. As an alternative, one could also set the
annotateForClosureCompiler option in the angularCompilerOptions to false - but it's not recommended. Read the Angular annotateForClosureCompiler documentation for further information.

$3

Especially when writing custom factories for NgModules, one might run into Angular metadata generation issues, usually resulting in errors
like Lambda not supported or Reference to a non-exported function.

!Angular Package Builder - metadata generation error

#### Solution

This issue can be solved by extracing the mentioned arrow function into a separate function, and making sure that it's exported.

> Also see this Angular issue on GitHub.

$3

Rarely, and only when using arrow functions within static classes and / or methods, an error like Function call not supported might occur.

#### Solution

This issue can be solved in two ways:

- Prefered: Add the @dynamicJSdoc tag to the comment describing the static method (or, if this should not work, the class containing the
static method). Then, the Angular Compiler will make an exception for this piece of code when validating the generated metadata.
- Alternative: Set the strictMetadataEmit option in the angularCompilerOptions object to false. Then, however, other metadata
validation issues will no longer be visible. Read the
Angular strictMetadataEmit documentation for further information.

> Also see this Angular issue on GitHub.

$3

Often, we integrate long-existing libraries into our Angular projects. Moment.js, for instance, is one of the
libraries used when working with dates. Due to its age, however, it's still published as a single-entry ES5 module - which means people
usually write the following TypeScript code to import the library:

` typescript
import * as moment from 'moment';
`

When trying to package an Angular library using the import statement above, an error will be thrown:

!Angular Package Builder - synthetic imports

#### Solution

The solution to this problem is called synthetic default imports,
a technique which does allow TypeScript to make default import from modules that come without a default export.

First, enable synthetic default import support in the TypeScript configuration by adding the following line to the
typescriptCompilerOptions within your .angular-package.json file:

` json
"typescriptCompilerOptions": {
"allowSyntheticDefaultImports": true
}
`

Then, change the affected import statements to default import statements. For instance:

` typescript
import moment from 'moment';
``

Alternatively, you could also consider Moment ES6 - it wraps around Moment.js and exports
it in an ES6-compatible (and thus TypeScript-compatible) way.

> Also see this Moment.js issue on GitHub.

Creator

Dominique Müller

- E-Mail: dominique.m.mueller@gmail.com
- Website: www.devdom.io
- Twitter: @itsdevdom