Build an Angular library compatible with AoT compilation & Tree shaking.
This starter allows you to create a library for Angular 4+ apps written in TypeScript, ES6 or ES5. The project is based on the official Angular packages.
Get the Changelog.
- 1 Project structure
- 2 Customizing
- 3 Testing
- 4 Building
- 5 Publishing
- 6 Documentation
- 7 Using the library
- 8 What it is important to know
- Library:
- src folder for the classes
- public_api.ts entry point for all public APIs of the package
- package.json npm options
- rollup.config.js Rollup configuration for building the bundles
- tsconfig-build.json ngc compiler options for AoT compilation
- build.js building process using ShellJS
- Testing:
- tests folder for unit & integration tests
- karma.conf.js Karma configuration that uses webpack to build the tests
- spec.bundle.js defines the files used by webpack
- Extra:
- tslint.json TypeScript linter rules with Codelyzer
- travis.yml Travis CI configuration
-
Update Node & npm.
-
Rename
angular-library-starter
andangularLibraryStarter
everywhere tomy-library
andmyLibrary
. -
Update in
package.json
file:- version: Semantic Versioning
- description
- urls
- packages
and run
npm install
. -
Create your classes in
src
folder, and export public classes inmy-library.ts
. -
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.
-
Update in
rollup.config.js
fileglobals
external dependencies with those that actually you use. -
Create unit & integration tests in
tests
folder, or unit tests next to the things they test insrc
folder, always using.spec.ts
extension. Karma is configured to use webpack only for*.ts
files.
The following command run unit & integration tests that are in the tests
folder, and unit tests that are in src
folder:
npm test
The following command:
npm run build
- starts TSLint with Codelyzer
- starts AoT compilation using ngc compiler
- 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
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
To generate the documentation, this starter uses compodoc:
npm run compodoc
npm run compodoc-serve
npm install my-library --save
System.config({
map: {
'my-library': 'node_modules/my-library/bundles/my-library.umd.js'
}
});
No need to set up anything, just import it in your code.
No need to set up anything, just import it in your code.
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.
The library is compatible with AoT compilation.
-
package.json
-
"main": "./bundles/angular-library-starter.umd.js"
legacy module format -
"module": "./bundles/angular-library-starter.es5.js"
flat ES module, for using module bundlers such as Rollup or webpack: package module -
"es2015": "./bundles/angular-library-starter.js"
ES2015 flat ESM format, experimental ES2015 build -
"peerDependencies"
the packages and their versions required by the library when it will be installed
-
-
tsconfig.json
file used by TypeScript compiler- Compiler options:
-
"strict": true
enables TypeScriptstrict
master option
-
- Compiler options:
-
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:
-
"skipTemplateCodegen": true,
skips generating AoT files -
"annotateForClosureCompiler": true
for compatibility with Google Closure compiler -
"strictMetadataEmit": true
without emitting metadata files, the library will not compatible with AoT compilation
-
-
-
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
-
-
Server-side prerendering
If you want the library will be compatible with server-side prerendering:
-
window
,document
,navigator
and other browser types do not exist on the server - don't manipulate the nativeElement directly
-
- angular-l10n An Angular library to translate messages, dates and numbers
- angular-auth-oidc-client An OpenID Connect Implicit Flow client for Angular
MIT