How to build and publish an Angular module

(This post is about Angular 2.)

When I created angular-async-local-storage, it was easy to create an Angular module and use it directly in my app. But as it could help other developers, I wanted it to be a reusable module, packaged and consumed like any other Angular modules.

I struggled with this building part. I found almost no documentation about this, so I tried to copy how the official Http module works. Now it’s done, I’m sharing my experience on how to build and publish an Angular module.

This post is for experienced developers, who already know the core concepts of Angular and how to create a basic app. A French version of this post is available here.

Creating your Angular module: pitfalls

This part is quite the same as creating a module in your app : import the modules you need, declare components, directives or pipes, or provide some services. There is just a few points to be aware of.

First, never import BrowserModule. Your module is a feature module, only the final user should import BrowserModule, in the app root module. If you need the common directives (*ngIf, *ngFor…), import CommonModule.

If your module is about creating new components, directives or pipes, do not forget to export them. Declared ones are only accessible inside your module.

Most importantly, do not mix components/directives/pipes and services in the same module. Why?

  • A service provided in a module will be available everywhere in the app, so your module should be imported only once, in the user app root module (like the Http module).
  • An exported component/directive/pipe will only be available in the module importing yours, so your module should be imported in every user module (root and/or feature modules) that need them (like the CommonModule).

If this is not clear for you, you should read the official NgModule documentation chapter, and the FAQ, as it’s an important (and confusing) point in Angular.

Finally, respect the Angular rule: never use browser-specific APIs (like the DOM) directly. If you do so, your module won’t be compatible with Universal server rendering and other Angular advanced options. If you really need to use browser-specific APIs (localStorage…), you should try/catch errors.

Exporting the public API

When you use an official Angular module, you just have one entry point to import all what you need (like '@angular/http').

So you’ll need to create an index.ts file, exporting all the public API of your module. It should at least contain your NgModule, and your components or services (the user will need to import them to inject them where they are needed).

Components/directives/pipes won’t be imported directly by the user, but you need to export them to be AoT compatible (thanks to Isaac Mann for this info).

Build tools

It’s where I started to struggle. So I managed to copy how official Angular modules work, like the HttpModule. They use:

npm install @angular/compiler @angular/compiler-cli typescript rollup uglify-js --save-dev

TypeScript configuration

Here’s the tsconfig.json of my module:

There are some important differences with your classic tsconfig.json:

  • explicit "paths" to other modules you use are needed, as the final bundle won’t include them directly (more on that later).
  • "angularCompilerOptions": { "strictMetadataEmit": true } is needed to be AoT compatible.
  • "declaration": true is important to generate type definitions files, so the user will have Intellisense for your module.
  • "noImplicitAny": true and "strictNullChecks": true are recommended (although not mandatory), to avoid errors, and to be compatible with all user configurations.
  • "module": "es2015" is important for performance, and "sourceMap": true for debugging, but nothing specific here.
  • "stripInternal": true avoid useless declarations for internal APIs and "skipLibCheck": true avoid being blocked by (harmless) errors in the librairies you use.

Rollup configuration

Angular modules are delivered in UMD format, so your rollup.config.js should be set consequently. Here is an example:

The entry script is your transpiled index.ts, so it should match your TypeScript configuration. bundles/modulename.umd.js is the conventional path and name used by Angular modules.

Rollup requires a moduleName for the UMD format. It will be a JavaScript object, so do not use special characters (no dashes).

Then, it’s where the important point takes place. Your module use Angular things (at least the NgModule decorator), but your bundle should not include Angular.

Why? Angular will already be included by the user app. If your module includes it too, it will be there twice, and there will be fatal (and incomprehensible) errors.

So you need to set Angular as a global. And you need to know the UMD module name for each module. It follows this convention: ng.modulename (ng.core, ng.common, ng.http...).

Same goes for RxJS, if your module uses it. And module names are quite a mess here. For classes (Observable…), it’s Rx. For operators (map, filter…), it’s Rx.Observable.prototype. For direct methods of classes (of, fromEvent…), it’s Rx.Observable.

Building, finally

You can now build your module bundle. You can save command lines in npm scripts :

Then:

npm run build

Note that transpiling is not done directly by TypeScript, you should use the Angular compiler (ngc) : it’s TypeScript with some additional Angular magic.

Publishing on npm

Do not publish everything on npm, only the dist directory.

You’ll need to create a new and specific dist/package.json. For example :

Some specific points :

  • "version" must follow semantic versioning. Any breaking change means a major number increment (even if it’s a small change). And when you’ll modify your module to stay up to date with Angular, it’s a minor number increment.
  • "main" and "module" paths are needed for user imports. "typings" path is for Intellisense.
  • "licence": "MIT": an open-source licence is important, or your module is useless. Angular uses the MIT licence, and you should stick to it.
  • Angular modules you’ve used will be listed in the peerDependencies. Still follow semver, with the ^ sign, or your module will be obsolete each time Angular upgrades. For other libraries (RxJS, zone.js…), you can see the current requirements of Angular here.

Do not forget to write a README, with the documentation of your API. Otherwise your module is useless. You can use a library like copyfiles to copy your README from your root project directory (displayed on Github) to your dist directory (displayed on npm repository).

And with a configured npm account, you can now publish your module:

cd dist
npm publish

And anytime you need to update your module, just rebuild, change the version number, update the changelog and publish again.