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
Transpile your libraries to Angular Package Format
Credits
Contributors
This project exists thanks to all the people who contribute. [Contribute].
Backers
Thank you to all our backers! π [Become a backer]
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]
Usage Example
Let's walk through a getting started that'll build an Angular library from TypeScript sources and create a distribution-ready npm package:
create a package.json
file, add the custom ngPackage
property, and eventually run ng-packagr -p package.json
β Here we go:
{
"$schema": "./node_modules/ng-packagr/package.schema.json",
"name": "@my/foo",
"version": "1.0.0",
"ngPackage": {
"lib": {
"entryFile": "public_api.ts"
}
}
}
Note 1: Paths in the ngPackage
section are resolved relative to the location of the package.json
file.
In the above example, public_api.ts
is the entry file to the library's sources and must be placed next to package.json
(a sibling in the same folder).
Note 2: referencing the $schema
enables JSON editing support (auto-completion for configuration) in IDEs like VSCode.
You can easily run ng-packagr through a npm/yarn script:
{
"scripts": {
"build": "ng-packagr -p package.json"
}
}
Now, execute the build with the following command:
$ yarn build
The build output is written to the dist
folder, containing all those binaries to meet the Angular Package Format specification.
You'll now be able to go ahead and npm publish dist
your Angular library to the npm registry.
Do you like to publish more libraries?
Is your code living in a monorepo?
Create one package.json
per npm package, run ng-packagr for each!
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
) - :trophy: Auto-discovers and bundles secondary entry points such as
@my/foo
, @my/foo/testing
, @my/foo/bar
- :mag_right: Creates scoped and non-scoped packages for publishing to npm registry
- :surfer: Inlines Templates and Stylesheets
- :sparkles: CSS Features
- :camel: Runs SCSS preprocessor, supporting the relative
~
import syntax and custom include paths - :elephant: Runs less preprocessor, supports the relative
~
import syntax - :snake: Runs Stylus preprocessor, resolves relative paths relative to ng-package.json
- :monkey: Adds vendor-specific prefixes w/ autoprefixer and browserslist β just tell your desired
.browserslistrc
- :tiger: Embed assets data w/ postcss-url
How toβ¦
Advanced Use Cases
Examples and Tutorials
A great step-by-step example of making an Angular CLI project with a library distributed separate from the app, by Jason Aden
Nikolas LeBlanc wrote a tutorial on 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!
Further user questions and issue-driven 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.
Contributing to ng-packagr
General contribution guidelines
If you like to submit a pull request, you'll find it helpful to take a look at the initial design document where it all started.
To orchestrate the different tools, ng-packagr features a custom transformation pipeline. The transformation pipeline is built on top of RxJS and Angular Dependency Injection concepts.
Knowledge
Angular Package Format v6.0, design document at Google Docs
Packaging Angular Libraries - Jason Aden at Angular Mountain View Meetup (Jan 2018, 45min talk)
Create and publish Angular libs like a Pro - Juri Strumpflohner at NG-BE (Dec 2017, 30min talk)
Packaging Angular - Jason Aden at ng-conf 2017 (28min talk)
Create and publish Angular libs like a Pro - Juri Strumpflohner at ngVikings, this time demoing building Angular libraries with ng-packagr, with NX as well as Bazel (March 2018, 30min talk)