Home

Awesome

angular-library-starter

Build Status

Build an Angular library compatible with AoT compilation & Tree shaking like an official package.

This starter allows you to create a library for Angular apps. The project is based on the official Angular packages.

Get the Changelog.

Contents

<a name="1"></a>1 Project structure

<a name="2"></a>2 Customizing

  1. Update Node & npm.

  2. Rename angular-library-starter and angularLibraryStarter everywhere to my-library and myLibrary.

  3. Customize the license-banner.txt file with your library license.

  4. Update in package.json file:

    • version: Semantic Versioning
    • description
    • urls
    • packages (optional): make sure you use a version of TypeScript compatible with Angular Compiler

    and run npm install.

  5. Create your classes in src folder, and export public classes in my-library.ts.

  6. You can create only one module for the whole library: I suggest you create different modules for different functions, so that the host app can only import the modules it uses, and optimize its Tree shaking.

  7. Update in rollup.config.js file globals external dependencies with those that actually you use to build the umd bundle.

  8. Create unit & integration tests in tests folder, or unit tests next to the things they test in src folder, always using .spec.ts extension.

<a name="3"></a>3 Testing

The following command runs unit & integration tests that are in the tests folder (you can change the folder in spec.bundle.js file):

npm test

or in watch mode:

npm run test:watch

It also reports coverage using Istanbul.

<a name="4"></a>4 Building

The following command:

npm run build

└── dist
    ├── bundles
    |   ├── my-library.umd.js
    |   ├── my-library.umd.js.map
    |   ├── my-library.umd.min.js
    |   └── my-library.umd.min.js.map
    ├── esm5
    |   ├── **/*.js
    |   └── **/*.js.map
    ├── esm2015
    |   ├── **/*.js
    |   └── **/*.js.map
    ├── fesm5
    |   ├── my-library.js
    |   └── my-library.js.map
    ├── fesm2015
    |   ├── my-library.js
    |   └── my-library.js.map
    ├── src
    |   └── **/*.d.ts
    ├── my-library.d.ts
    ├── my-library.metadata.json
    ├── LICENSE
    ├── package.json
    ├── public_api.d.ts
    └── README

To test locally the npm package before publishing:

npm run pack:lib

Then you can install it in an app to test it:

npm install [path]my-library-{version}.tgz

<a name="5"></a>5 Publishing

Before publishing the first time:

npm run publish:lib

<a name="6"></a>6 Documentation

To generate the documentation, this starter uses compodoc:

npm run compodoc
npm run compodoc:serve

<a name="7"></a>7 Using the library

Installing

npm install my-library --save

Loading

Angular-CLI

No need to set up anything, just import it in your code.

Rollup or webpack

No need to set up anything, just import it in your code.

Using SystemJS configuration

System.config({
    map: {
        'my-library': 'node_modules/my-library/bundles/my-library.umd.js'
    }
});

Plain JavaScript

Include the umd bundle in your index.html:

<script src="node_modules/my-library/bundles/my-library.umd.js"></script>

and use global ng.myLibrary namespace.

AoT compilation

The library is compatible with AoT & Ivy.

<a name="8"></a>8 What it is important to know

  1. package.json

    • "main": "./bundles/angular-library-starter.umd.js" legacy module format
    • "module": "./esm5/angular-library-starter.js" flat ES module, for using module bundlers such as Rollup or webpack
    • "es2015": "./esm2015/angular-library-starter.js" ES2015 flat ESM format
    • "typings" declaration files for TypeScript compiler
    • "peerDependencies" the packages and their versions required by the library when it will be installed

  2. tsconfig.json file used by TypeScript compiler

    • Compiler options:
      • "strict": true enables TypeScript strict master option

  3. tsconfig-build.json file used by ngc compiler

    • Compiler options:

      • "declaration": true to emit TypeScript declaration files
      • "module": "es2015" & "target": "es2015" are used by Rollup to create the ES2015 bundle

    • Angular Compiler Options:

      • "enableResourceInlining": true inlining of templates & styles
      • "skipTemplateCodegen": true skips generating AoT files
      • "strictMetadataEmit": true without emitting metadata files, the library will not be compatible with AoT compilation: it is intended to report syntax errors immediately rather than produce a .metadata.json file with errors
      • "flatModuleId": "@scope/package" full package name has to include scope as well, otherwise AOT compilation will fail in the consumed application
      • "enableIvy": false libraries don't need to enable Ivy

  4. rollup.config.js file used by Rollup

    • format: 'umd' the Universal Module Definition pattern is used by Angular for its bundles
    • moduleName: 'ng.angularLibraryStarter' defines the global namespace used by JavaScript apps
    • external & globals declare the external packages

  5. Server Side Rendering

    If you want the library will be compatible with Server Side Rendering:

    • window, document, navigator and other browser types do not exist on the server
    • don't manipulate the nativeElement directly

<a name="9"></a>9 Inlining of templates and stylesheets

Now ngc compiler supports inlining of templates & styles. Moreover, this starter allows you to use .scss sass files. If you need, you can use different pre-processors.

<a name="built-with-this-starter"></a>Built with this starter

<a name="previous-versions"></a>Previous versions

License

MIT