angular-library-starter

Build a library compatible with Angular, AoT compilation & Tree shaking.

This starter allows you to create a library for Angular 2+ apps written in TypeScript, ES6 or ES5. The project is based on the official Angular modules.

Get the Changelog.

Contents

• 1 Project structure
• 2 Customizing
• 3 Unit testing
• 4 Building
• 5 Publishing
• 6 Documentation
• 7 Using the library
• 8 What it is important to know

1 Project structure

• Library:
  • src folder for the classes
  • index.ts entry point for all public APIs of the package
  • package.json npm options
  • rollup.config.js Rollup configuration for building the bundle
  • tsconfig-build.json ngc compiler options for AoT compilation
  • build.js commands to build the library using ShellJS
• Unit testing:
  • tests folder for unit testing
  • karma.conf.js Karma configuration that uses webpack
  • spec.bundle.js defines the files used by webpack
  • tsconfig.json TypeScript compiler options
• Extra:
  • tslint.json TypeScript linter rules with Codelyzer
  • travis.yml Travis CI configuration

2 Customizing

1. Update Node & npm.

2. Rename angular-library-starter everywhere to my-library.

3. Update in package.json file:

   • version: Semantic Versioning
   • description
   • urls
   • packages

   and run npm install.

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

5. You can create only one module for the whole library: I suggest you create different modules for different functions, so that the user can import only those he needs and optimize Tree shaking of his app.

6. Update in rollup.config.js file external & globals libraries with those that actually you use.

7. Create unit tests in tests folder. Karma is configured to use webpack only for *.ts files: if you need to test different formats, you have to update it.

3 Unit testing

npm test 

4 Building

The following command:

npm run build

• starts TSLint with Codelyzer
• starts AoT compilation using ngc compiler
• creates umd bundle using Rollup
• minimizes umd bundle using UglifyJS
• creates dist folder with all the files of distribution

To test locally the npm package:

npm run pack-lib

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

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

5 Publishing

Before publishing the first time:

• you can register your library on Travis CI: you have already configured .travis.yml file
• you must have a user on the npm registry: Publishing npm packages

npm run publish-lib

6 Documentation

To generate the documentation, this starter uses compodoc:

npm run compodoc
npm run compodoc-serve 

7 Using the library

Installing

npm install my-library --save 

Loading

Using SystemJS configuration

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

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.

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.my-library namespace.

AoT compilation

The library is compatible with AoT compilation.

8 What it is important to know

1. package.json

   • "module": "index.js" to use import & export with ES2015 module bundlers
   • "peerDependencies" the packages and their versions required by the library when it will be installed

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

   • Compiler options:

     • "declaration": true to emit TypeScript declaration files
     • "module": "es2015" for compatibility with AoT compilation & Tree shaking
     • "target": "es5" for browsers compatibility

   • Angular Compiler Options:

     • "skipTemplateCodegen": true, skips generating ngfactories files
     • "annotateForClosureCompiler": true for compatibility with Google Closure compiler
     • "strictMetadataEmit": true without emitting metadata files, the library will not compatible with AoT compilation

3. rollup.config.js file used to build the bundle

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

4. 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: use Renderer

License

MIT