What is ng-packagr?
ng-packagr is a tool for building and packaging Angular libraries in a way that is compatible with the Angular Package Format (APF). It helps developers to create reusable Angular libraries that can be easily distributed and consumed by other Angular applications.
What are ng-packagr's main functionalities?
Library Packaging
This command packages an Angular library according to the configuration specified in the ng-package.json file. It compiles the TypeScript code, bundles the library, and generates metadata files.
ng-packagr -p ng-package.json
Configuration File
The ng-package.json file is used to configure the packaging process. It specifies the destination directory for the packaged library and the entry file for the library.
{
"$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
"dest": "dist/my-lib",
"lib": {
"entryFile": "src/public-api.ts"
}
}
Custom Build Steps
You can add custom build steps in your package.json file to automate the packaging process. This example shows how to add a build script that runs ng-packagr with the specified configuration file.
{
"scripts": {
"build": "ng-packagr -p ng-package.json"
}
}
Other packages similar to ng-packagr
ngx-build-plus
ngx-build-plus is an Angular CLI extension that allows for more advanced build customizations. It provides features like extending the Angular build process, adding custom webpack configurations, and more. Compared to ng-packagr, ngx-build-plus is more focused on extending and customizing the build process of Angular applications rather than packaging libraries.
angular-library-builder
angular-library-builder is another tool for building Angular libraries. It provides a simple and straightforward way to package Angular libraries, similar to ng-packagr. However, it may not support all the advanced features and configurations that ng-packagr offers.
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"
}
}
$ yarn build
Alternatively, build the library with the following command:
$ node_modules/.bin/ng-packagr -p ng-package.json
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
.
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.
More Examples
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
.
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.
Features
- :gift: Implements Angular Package Format
- :checkered_flag: Bundles your library in FESM2015, FESM5, and UMD formats
- :school_satchel: npm package can be consumed by Angular CLI, Webpack, or SystemJS
- :dancer: Creates type definitions (
.d.ts
) - :runner: Generates Ahead-of-Time metadata (
.metadata.json
)
- :surfer: Inlines Templates and Stylesheets
- :sparkles: CSS Features
Knowledge
Angular Package Format v4.0, design document at Google Docs
Packaging Angular - Jason Aden at ng-conf 2017 (28min talk):