ng-packagr

Transpile your libraries to Angular Package Format

Usage Example

For publishing your Angular library, create a package.json file and add the custom ngPackage property:

{
  "$schema": "./node_modules/ng-packagr/package.schema.json",
  "name": "@my/foo",
  "version": "1.0.0",
  "ngPackage": {
    "lib": {
      "entryFile": "public_api.ts"
    }
  }
}

Paths in the ngPackage configuration are resolved relative to the location of the package.json file. You should use a npm/yarn script to run ng-packagr:

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

Now, build with the following command:

$ yarn build

You like to publish more libraries to npm? Create one package.json per npm package, run ng-packagr for each!

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)
  • 🏆 Auto-discovers and bundles secondary entry points such as @my/foo, @my/foo/testing, @my/foo/bar
• 🔎 Creates scoped and 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's story on medium.com: Building an Angular 4 Component Library with the Angular CLI and ng-packagr

Here is a demo repository showing ng-packagr and Angular CLI in action.

What about ng-packagr alongside Nx Workspace? Well, they work well together!

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 a ng-package.json, put the package.json of the library in the same folder next to the ng-package.json. Contents of ng-package.json are for example:

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

To configure with a package.json, put the configuration in the ngPackage custom property:

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

Note: referencing the $schema enables JSON editing support (auto-completion for configuration) in IDEs like VSCode.

Secondary Entry Points

Beside 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. The module id of a secondary entry directs the module loader to a sub-directory by the secondary's name. For instance, @angular/core/testing resolves to a directory under node_modules/@angular/core/testing containing 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 secondary entry points (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.

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

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

{
  "ngPackage": {}
}

No, that is not a typo. No name is required. No version is required. It's all handled for you by ng-packagr! When built, the primary entry is imported with @my/library and the secondary entry with @my/library/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"
    }
  }
}

React loves Angular, Angular loves React

What if I want to use React Components in Angular?

If you have React Components that you're using in your library, and want to use proper JSX/TSX syntax in order to construct them, you can set the jsx flag for your library through ng-package.json like so:

{
  "$schema": "../../../src/ng-package.schema.json",
  "lib": {
    "entryFile": "public_api.ts",
    "externals": {
      "react": "React",
      "react-dom": "ReactDOM"
    },
    "jsx": "react"
  }
}

The jsx flag will accept what the corresponding tsconfig accepts, more information in the TypeScript Handbook chaper on JSX.

Note: Don't forget to include react and react-dom in your externals so that you're not bundling those dependencies!

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 v5.0, design document at Google Docs

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