WarningThis library is under active development and hasn't yet reached its final form. It may not be fully compatible with current versions of Angular.
22ndtech Angular Library!Build Statustravis-badgetravis-badge-url This is a simple library for using 22ndtech services from Angular, implementing the Angular Package Format v4.0. Currently only unscoped, primary entry-point libraries are supported. Features:
- a simple example library
- unit tests for the library
- a demo application that consumes the library in JIT mode and runs in watch mode
- an integration app that consumes the library in JIT and AOT mode and runs e2e tests
npm startto run a live-reload server with the demo app
npm run testto test in watch mode, or
npm run test:onceto only run once
npm run buildto build the library
npm run lintto lint
npm run cleanto clean
npm run integrationto run the integration e2e tests
npm install ./relative/path/to/libafter
npm run buildto test locally in another app
The 22ndtech Angular LibraryThis example repository has an implemention of the described package format but is by no means the only way you should publish a library. Any setup that builds the necessary package format works just as well for a consumer. You are encouraged to customize this process as you see fit. When developing your own setup, keep in mind that even though AOT is preferred, Just-in-time compilation should be supported. Make sure you have at least Node 6.9 and NPM 3.0 installed. Then ...
- Create a project folder (you can call it
22ndtech-angular-liband rename it later).
- Install npm packages.
npm startto launch the sample application.
ClonePerform the clone-to-launch steps with these terminal commands. ``` git clone https://github.com/angular/22ndtech-angular-lib.git 22ndtech-angular-lib cd angular-22ndtech-angular-lib npm install npm start ```
DownloadDownload the 22ndtech Angular Library seed and unzip it into your project folder. Then perform the remaining steps with these terminal commands. ``` cd 22ndtech-angular-lib npm install npm start ```
Initialize your repositoryIf you cloned the package from github, it has a
.gitfolder where the official repository's history lives. You don't want that git history though - you'll want to make your own. Delete this folder and initialize this one as a new repository: ``` rm -rf .git # Linux or OS/X (bash) rd .git /S/Q # Windows git init ``` Warning: Do this only in the beginning to avoid accidentally deleting your own git setup!
What's in the 22ndtech Angular Library?The 22ndtech Angular Library contains a similar structure to the Quickstart seed. It's modified to build and test a library instead of an application. Consequently, there are many different files in the project. Focus on the following TypeScript (
.ts) files in the
/srcfolder. ``` src/ ├── demo/ | └── app/ | ├── app.component.ts | └── app.module.ts └── lib/
| └── lib.component.ts
| └── lib.service.ts
``` Each file has a distinct purpose and evolves independently as the application grows. Files outside
src/concern building, deploying, and testing your app. They include configuration files and external dependencies. Files inside
src/lib/"belong" to your library, while
src/demo/contains a demo application that loads your library. Libraries do not run by themselves, so it's very useful to have this "demo" app while developing to see how your library would look like to consumers. When you run
npm start, the demo application is served. The following are all in
The build stepYou can build the library by running
npm run build. This will generate a
dist/directory with all the entry points described above. All the logic for creating the build can be found in
./build.js. It consists of roughly 5 steps:
- Compile with the AOT Compiler (AOT compiler or
ngc) for ES5 and ES2015.
- Copy typings, metatada, html and css.
- Create each bundle using Rollup.
Testing librariesWhile testing is always important, it's especially important in libraries because consumer applications might break due to bugs in libraries. But the fact that a library is consumed by another application is also what makes it hard to test. To properly test a library, you need to have an integration tests. An integration test is to libraries what an end-to-end test is to applications. It tests how an app would install and use your library. The 22ndtech Angular Library includes a directory called
integrationcontaining a standalone app that consumes your built library in both AOT and JIT modes, with end-to-end tests to verify it works. To run the integration tests, do
npm run integrationwhich does the following:
- Build your library.
- Enter the integration app's directory.
- Install dependencies.
- Build the app in AOT mode.
- Test the app in AOT mode.
- Test the app in JIT mode.
npm run test, or single-run via
npm run test:once. You can also test your library by installing it in another local repository you have. To do so, first build your lib via
npm run build. Then install it from your other repo using a relative path to the dist folder:
npm install relative/path/to/library/dist.
Publishing your libraryEvery package on NPM has a unique name, and so should yours. If you haven't already, now is the time to change the name of your library. Use your editor to search the project for all instances of
angular-22ndtech-angular-liband change it to your intended name (also in
dash-caseformat). The library name is mentioned on at least these files:
Updating the packageon that previous doc, here we use standard-version. Read their docs to see how to use it. First you'll need to create a NPM account and login on your local machine. Then you can publish your package by running
npm publish dist/. Since your package is built on the
dist/folder this is the one you should publish.
Be a good library maintainerNow that you've published a library, you need to maintain it as well. Below are some of the most important points:
- Document your library.
- Keep an eye on the issue tracker.
- Follow Semantic Versioning
- Setup a Continuous Integration solution to test your library (included is a
- Choose an appropriate license.
Appendix: Supporting AOTAOT plays an important role in optimizing Angular applications. It's therefore important that third party libraries be published in a format compatible with AOT compilation. Otherwise it will not be possible to include the library in an AOT compiled application. Only code written in TypeScript can be AOT compiled. Before publishing the library must first be compiled using the AOT compiler (
.d.tstypings files. Meta Data JSON files
ngcoutputs a metadata.json file for every
NgModule. These meta data files represent the information in the original
Componentdecorators. The meta data may reference external templates or css files. These external files must be included with the library.
ngcgenerates a series of files with an
.ngfactorysuffix as well. These files represent the AOT compiled source, but should not be included with the published library. Instead the
ngccompiler in the consuming application will generate
Why not publish TypeScript?Why not ship TypeScript source instead? After all the library will be part of another TypeScript compilation step when the library is imported by the consuming application. Generally it's discouraged to ship TypeScript with third party libraries. It would require the consumer to replicate the complete build environment of the library. Not only typings, but potentially a specific version of
Appendix: Supporting JITAOT compiled code is the preferred format for production builds, but due to the long compilation time it may not be practical to use AOT during development. To create a more flexible developer experience a JIT compatible build of the library should be published as well. The format of the JIT bundle is
umd, which stands for Universal Module Definition. Shipping the bundle as
umdensures compatibility with most common module loading formats. The
Appendix: Dependency ManagementAs a library maintainer, it's important to properly manage your dependencies in
package.json. There are three kinds of dependencies:
dependencies: here go all the other libraries yours depends on when being used.
src/libonly) and list all the libraries there.
devDependencies: libraries that you need while developing, testing and building your library
peerDependencies: these are similar to
dependenciessince your library expects them to be
@angular/coreand all other main Angular libraries. If you listed these in
dependencies, a new one - with a different version! - could be installed for your library to use. This isn't what you wanted though. You want your library to use the exact same
@angular/corethat the app is using. You'll usually used
@angular/*libraries listed in both
peerDependencies. This is normal and expected, because when you're developing your library also need a copy of them installed. Another thing to remember is to keep your dependencies from changing too much unexpectedly. Different versions of libraries can have different features, and if you inadvertently are too lenient with allowed versions your library might stop working because a dependency changed. You can choose what versions you allow by using ranges. A good rule of thumb is to have all
dependenciesspecified with a tilde
~1.2.3), while your
peerDependencieshave a range (
"@angular/core": ">=4.0.0 <5.0.0 || >=4.0.0-beta <5.0.0"). Any extra dependency or peer dependency that you add to
package.jsonshould also be added to the
externalarray in the
./build.js. This ensures your library doesn't package extra libraries inside of it and instead uses the ones available in the consuming app.