ha-confirmation
v0.0.3
Published
[![Build Status](https://travis-ci.org/robisim74/angular-library-starter.svg?branch=master)](https://travis-ci.org/robisim74/angular-library-starter) >Build an Angular library compatible with AoT compilation & Tree shaking like an official package.
Downloads
1
Maintainers
Readme
angular-library-starter
Build an Angular library compatible with AoT compilation & Tree shaking like an official package.
This starter allows you to create a library for Angular v5 apps written in TypeScript, ES6 or ES5. The project is based on the official Angular packages.
Get the Changelog.
Contents
- 1 Project structure
- 2 Customizing
- 3 Testing
- 4 Building
- 5 Publishing
- 6 Documentation
- 7 Using the library
- 8 What it is important to know
- 9 Inlining of templates and stylesheets
1 Project structure
- 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 umd bundles
- rollup.es.config.js Rollup configuration for building the es2015 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 Angular TSLint Preset (TypeScript linter rules with Codelyzer)
- travis.yml Travis CI configuration
2 Customizing
Update Node & npm.
Rename
angular-library-starter
andangularLibraryStarter
everywhere tomy-library
andmyLibrary
.Customize the
license-banner.txt
file with your library license.Update in
package.json
file:- version: Semantic Versioning
- description
- urls
- packages (optional): make sure you use a version of TypeScript compatible with Angular Compiler (@angular/[email protected] requires a peer of typescript@>=2.4.2 <2.5)
and run
npm install
.Create your classes in
src
folder, and export public classes inmy-library.ts
: if you have components, note that this starter supports only inline templates & styles as the official Angular building process.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.
Update in
rollup.config.js
fileglobals
external dependencies with those that actually you use to build the umd bundle.Create unit & integration tests in
tests
folder, or unit tests next to the things they test insrc
folder, always using.spec.ts
extension: note that Karma is configured to use webpack only for*.ts
files.
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
It also reports coverage using Istanbul.
4 Building
The following command:
npm run build
- starts TSLint with Codelyzer using Angular TSLint Preset
- starts AoT compilation using ngc compiler
- creates
dist
folder with all the files of distribution, following Angular Package Format (APF) v5.0:
└── dist
├── bundles
| ├── my-library.umd.js
| ├── my-library.umd.js.map
| ├── my-library.umd.min.js
| └── my-library.umd.min.js.map
├── esm5
| ├── my-library.js
| └── my-library.js.map
├── esm2015
| ├── 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
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.myLibrary
namespace.
AoT compilation
The library is compatible with AoT compilation.
8 What it is important to know
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: package module"es2015": "./esm2015/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 compilerCompiler 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 be compatible with AoT compilation: it is intended to report syntax errors immediately rather than produce a .metadata.json file with errors
rollup.config.js
file used by Rollupformat: 'umd'
the Universal Module Definition pattern is used by Angular for its bundlesmoduleName: 'ng.angularLibraryStarter'
defines the global namespace used by JavaScript appsexternal
&globals
declare the external packages
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
9 Inlining of templates and stylesheets
From Angular Package Format v5.0:
Component libraries are typically implemented using stylesheets and html templates stored in separate files. While it's not required, we suggest that component authors inline the templates and stylesheets into their FESM files as well as *.metadata.json files by replacing the stylesheetUrls and templateUrl with stylesheets and template metadata properties respectively. This simplifies consumption of the components by application developers.
ngc compiler still does not support inlining of templates & styles. But if you want, you can follow this suggestion: Inlining of templates and stylesheets.
Built with this starter
- angular-l10n An Angular library to translate messages, dates and numbers
- angular-auth-oidc-client An OpenID Connect Implicit Flow client for Angular
- ngx-infinite-scroll An infinite scroll directive for Angular compatible with AoT compilation and Tree shaking
- ngx-typeahead A simple but yet powerful typeahead component for Angular
- ng2-youtube-player A Powerful Youtube Player Component for Angular
- ng2-completer Angular autocomplete component
Previous versions
License
MIT