1 | # ng-packagr
|
2 |
|
3 | > Compile and package Angular libraries in Angular Package Format (APF)
|
4 |
|
5 |
|
6 | [![npm](https://img.shields.io/npm/v/ng-packagr.svg?style=flat-square)](https://www.npmjs.com/package/ng-packagr)
|
7 | [![npm License](https://img.shields.io/npm/l/ng-packagr.svg?style=flat-square)](https://github.com/ng-packagr/ng-packagr/blob/master/LICENSE)
|
8 | [![CircleCI](https://img.shields.io/circleci/project/github/ng-packagr/ng-packagr/master.svg?label=Circle%20CI&style=flat-square)](https://circleci.com/gh/ng-packagr/ng-packagr)
|
9 |
|
10 | [![GitHub stars](https://img.shields.io/github/stars/ng-packagr/ng-packagr.svg?label=GitHub%20Stars&style=flat-square)](https://github.com/ng-packagr/ng-packagr)
|
11 | [![npm Downloads](https://img.shields.io/npm/dw/ng-packagr.svg?style=flat-square)](https://www.npmjs.com/package/ng-packagr)
|
12 | [![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen.svg?style=flat-square)](https://renovateapp.com/)
|
13 |
|
14 | ## Credits
|
15 |
|
16 | ### Contributors
|
17 |
|
18 | This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
|
19 |
|
20 | <a href="https://github.com/ng-packagr/ng-packagr/graphs/contributors"><img src="https://opencollective.com/ng-packagr/contributors.svg?width=890&button=false" /></a>
|
21 |
|
22 | ## Installation
|
23 |
|
24 | ```bash
|
25 | npm install -D ng-packagr
|
26 | ```
|
27 |
|
28 | ## Usage Example
|
29 |
|
30 | Let's walk through a _getting started_ that'll build an Angular library from TypeScript sources and create a distribution-ready npm package:
|
31 | create a `package.json` file, add the custom `ngPackage` property, and eventually run `ng-packagr -p package.json`
|
32 | – Here we go:
|
33 |
|
34 | ```json
|
35 | {
|
36 | "$schema": "./node_modules/ng-packagr/package.schema.json",
|
37 | "name": "@my/foo",
|
38 | "version": "1.0.0",
|
39 | "ngPackage": {
|
40 | "lib": {
|
41 | "entryFile": "public_api.ts"
|
42 | }
|
43 | }
|
44 | }
|
45 | ```
|
46 |
|
47 | Note 1: Paths in the `ngPackage` section are resolved relative to the location of the `package.json` file.
|
48 | 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).
|
49 |
|
50 | Note 2: referencing the `$schema` enables JSON editing support (auto-completion for configuration) in IDEs like [VSCode](https://github.com/Microsoft/vscode).
|
51 |
|
52 | You can easily run _ng-packagr_ through a npm/yarn script:
|
53 |
|
54 | ```json
|
55 | {
|
56 | "scripts": {
|
57 | "build": "ng-packagr -p package.json"
|
58 | }
|
59 | }
|
60 | ```
|
61 |
|
62 | Now, execute the build with the following command:
|
63 |
|
64 | ```bash
|
65 | $ yarn build
|
66 | ```
|
67 |
|
68 | The build output is written to the `dist` folder, containing all those _binaries_ to meet the Angular Package Format specification.
|
69 | You'll now be able to go ahead and `npm publish dist` your Angular library to the npm registry.
|
70 |
|
71 | Do you like to publish more libraries?
|
72 | Is your code living in a monorepo?
|
73 | Create one `package.json` per npm package, run _ng-packagr_ for each!
|
74 |
|
75 | ## Features
|
76 |
|
77 | * :gift: Implements [Angular Package Format](https://angular.io/guide/angular-package-format)
|
78 | * :checkered_flag: Bundles your library in FESM2020
|
79 | * :school_satchel: npm package can be consumed by [Angular CLI](https://github.com/angular/angular-cli), [Webpack](https://github.com/webpack/webpack), or [SystemJS](https://github.com/systemjs/systemjs)
|
80 | * :dancer: Creates type definitions (`.d.ts`)
|
81 | * :trophy: Auto-discovers and bundles secondary entry points such as `@my/foo`, `@my/foo/testing`, `@my/foo/bar`
|
82 | * :mag_right: Creates [scoped and non-scoped packages](https://docs.npmjs.com/misc/scope) for publishing to npm registry
|
83 | * :surfer: Inlines Templates and Stylesheets
|
84 | * :sparkles: CSS Features
|
85 | * :camel: Runs [SCSS](http://sass-lang.com/guide) preprocessor, supporting the [relative `~` import syntax](https://github.com/webpack-contrib/sass-loader#imports) and custom include paths
|
86 | * :snake: Runs [Stylus](http://stylus-lang.com) preprocessor, resolves relative paths relative to ng-package.json
|
87 | * :monkey: Adds vendor-specific prefixes w/ [autoprefixer](https://github.com/postcss/autoprefixer#autoprefixer-) and [browserslist](https://github.com/ai/browserslist#queries) — just tell your desired `.browserslistrc`
|
88 | * :tiger: Embed assets data w/ [postcss-url](https://github.com/postcss/postcss-url#inline)
|
89 |
|
90 |
|
91 | ## How to…
|
92 | - [Copy Assets](docs/copy-assets.md)
|
93 | - [Embed Assets in CSS](docs/embed-assets-css.md)
|
94 | - [Managing Dependencies](docs/dependencies.md)
|
95 | - [Change the Entry File of a Library](docs/entry-file.md)
|
96 | - [Change Configuration Locations](docs/configuration-locations.md)
|
97 | - [Override tsconfig](docs/override-tsconfig.md)
|
98 | - [Add Style Include Paths](docs/style-include-paths.md)
|
99 | - [Package Secondary Entrypoints (sub packages)](docs/secondary-entrypoints.md)
|
100 |
|
101 | ## Knowledge
|
102 |
|
103 | [Angular Package Format documentation](https://angular.io/guide/angular-package-format)
|
104 |
|
105 | Packaging Angular Libraries - Jason Aden at Angular Mountain View Meetup ([Jan 2018, 45min talk](https://www.youtube.com/watch?v=QfvwQEJVOig&t=3612s))
|
106 |
|
107 | Create and publish Angular libs like a Pro - Juri Strumpflohner at NG-BE ([Dec 2017, 30min talk](https://youtu.be/K4YMmwxGKjY))
|
108 |
|
109 | [![Juri Strumpflohner - Create and publish Angular libs like a Pro](https://img.youtube.com/vi/K4YMmwxGKjY/0.jpg)](https://youtu.be/K4YMmwxGKjY)
|
110 |
|
111 | Packaging Angular - Jason Aden at ng-conf 2017 ([28min talk](https://youtu.be/unICbsPGFIA))
|
112 |
|
113 | [![Packaging Angular - Jason Aden](https://img.youtube.com/vi/unICbsPGFIA/0.jpg)](https://youtu.be/unICbsPGFIA)
|
114 |
|
115 |
|
116 | 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](https://youtu.be/Tw8TCgeqotg))
|
117 |
|
118 | [![Juri Strumpflohner - Create & Publish Angular Libs like a PRO at ngVikings](https://img.youtube.com/vi/Tw8TCgeqotg/0.jpg)](https://youtu.be/Tw8TCgeqotg)
|
119 |
|
120 | ## Contributing to ng-packagr
|
121 |
|
122 | [General contribution guidelines](./CONTRIBUTING.md)
|
123 |
|
124 | 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](./docs/DESIGN.md).
|
125 |
|
126 | To orchestrate the different tools, ng-packagr features a [custom transformation pipeline](docs/transformation-pipeline.md#a-transformation-pipeline). The transformation pipeline is built on top of RxJS and Angular Dependency Injection concepts.
|