ng-packagr

Compile and package a TypeScript library to Angular Package Format

Usage Example

For an Angular library, create one configuration file ng-package.json:

{
  "$schema": "./node_modules/ng-packagr/ng-package.schema.json",
  "lib": {
    "entryFile": "public_api.ts"
  }
}

Then, build the library from a npm/yarn script defined in package.json:

{
  "scripts": {
    "build": "ng-packagr -p ng-package.json"
  }
}

Now build with this command:

$ yarn build

Paths are resolved relative to the location of the ng-package.json file. The package.json describing the library should be located in the same folder, next to ng-package.json.

Features

• 🎁 Implements Angular Package Format
  • 🏁 Bundles your library in FESM2015, FESM5, and UMD formats
  • 🎒 npm package can be consumed by Angular CLI, Webpack, or SystemJS
  • 💃 Creates type definitions (.d.ts)
  • 🏃 Generates Ahead-of-Time metadata (.metadata.json)
• 🏆 Supports dynamic discovery and bundling of secondary entry points
• 🔎 Creates either a scoped or a non-scoped packages for publishing to npm registry
• 🏄 Inlines Templates and Stylesheets
• ✨ CSS Features
  • 🐫 Runs SCSS preprocessor, supporting the relative ~ import syntax
  • 🐘 Runs less preprocessor
  • 🐍 Runs Stylus preprocessor, resolves relative paths relative to ng-package.json
  • 🐒 Adds vendor-specific prefixes w/ autoprefixer and browserslist — just tell your desired .browserslistrc

Advanced Use Cases

Examples and Tutorials

Nikolas LeBlanc has written a story on medium.com on Building an Angular 4 Component Library with the Angular CLI and ng-packagr

The demo repository ng-packaged shows Angular CLI together with ng-packagr.

Configuration Locations

Configuration is picked up from the cli -p parameter, then from the default location for ng-package.json, then from package.json.

To configure with package.json, put your ng-package configuration in the ngPackage field:

{
  "$schema": "./node_modules/ng-packagr/package.schema.json",
  "ngPackage": {
    "lib": {
      "entryFile": "public_api.ts"
    }
  }
}

Note: the JSON $schema reference enables JSON editing support (autocompletion) for the custom ngPackage property in an IDE like VSCode.

Secondary Entry-Points

Besides the primary entry point, a package can contain one or more secondary entry points (e.g. @angular/core/testing, @angular/cdk/a11y, …). These contain symbols that we don't want to group together with the symbols in the main entry point. The module id of a secondary entry point directs the module loader to a sub-directory by the name of the secondary entry point. For instance, “@angular/core/testing” resolves to a directory by the same name, “@angular/core/testing”. This directory contains a package.json file that directs the loader to the correct location for what it's looking for.

For library developers, secondary entry points are dynamically discovered by searching for package.json files within sub directories of the main package.json file's folder!

So how do I use sub-packages?

All you have to do is create a package.json file and put it where you want a secondary entry point to be created. One way this can be done is by mimicking the folder structure of the following example which has a testing entry point in addition to its main entry point.

src  
├── testing   
│   ├── *.ts   
│   ├── public_api.ts  
│   └── package.json  
├── *.ts  
├── public_api.ts  
├── ng-package.json   
└── package.json   

The contents of the secondary package.json can be as simple as:

No, that is not a typo. No name is required. No version is required. Not even a json object is required. It's all handled for you by ng-packagr! When built, the secondary bundles would be accessible as $(your-primary-package-name)/testing.

What if I don't like public_api.ts?

You can change the entry point file by using the ngPackage configuration field in your secondary package.json. For example, the following would use index.ts as the secondary entry point:

{
  "ngPackage": {
    "lib": {
      "entryFile": "index.ts"
    }
  }
}

Further documentation

We keep track of user questions in GitHub's issue tracker and try to build a documentation from it. Explore issues w/ label documentation.

Knowledge

Angular Package Format v4.0, design document at Google Docs

Packaging Angular - Jason Aden at ng-conf 2017 (28min talk):