Getting your Angular 2 library ready for AoT
There are 2 basic things you need to get your Angular 2 library ready for consumers to use it in an AoT compiled application.
- Don’t use the runtime (JiT) compiler
- Make sure your NgModule is statically analyzable.
*.metadata.jsonfiles in your npm package (See this issue comment.)
All referenced libraries must include the *.metadata.json file along side any *.d.ts files they produce…
#1 is pretty obvious when you’re doing it and kind of rare. (See this article if you think you really need the runtime compiler.)
#2 can be difficult and gives rather unhelpful error messages. So I’ve written a separate article to help people satisfy this requirement.
#3 is less obvious and I haven’t found good documentation or any examples of libraries actually doing this. If you don’t do #3, users of your YourAwesomeModule library that try the AoT compiler will get this error:
Error: Unexpected value ‘YourAwesomeModule’ imported by the module ‘AppModule’
So, I’m writing down the steps for library maintainers (and excited pull-requesters) to follow.
1. Make sure that you have the required packages installed as
npm install --save-dev @angular/compiler-cli typescript@2 @angular/platform-server @angular/compiler
2. Generate *.ngFactory.ts files in their own directory
3. Don’t include generated code in version control
# These lines were probably already there
*.js # or /src/**/*.js
4. Don’t include *.ngFactory.ts files in the npm package
Consumers of the library will generate these on their own. Add to
# or no change needed if you already have
5. Use Angular 2’s wrapper around typescript
package.json scripts replace all references to
6. Run the compiler
Build your library the same way you always have, but now your
package.json scripts will use
ngc instead of
tsc. Make sure that the
*.metadata.json files are next to their associated
You’ll need to fix any errors in this step that are caused by #2 above. I’ve written a separate article that will help you deal with these (somewhat obtuse) errors.
Note: If you use webpack to build your library, you’ll need to run ngc first and then run webpack on the compiled code. This issue is tracking changes needed to have webpack manage the whole process. This repo is an example of using the npm run ngc && npm run webpack strategy.
7. Test the new package in an AoT enabled starter
I’ve used angular2webpack2-starter, but there are several others. Here are my steps:
- In your compiled library directory, run
npm pack. This will create your-awesome-library.tar.gz
- Somewhere else, run
git clone https://github.com/qdouble/angular2webpack2-starter.git
cd angular2webpack2-starter && npm install
npm install ../path/to/your-awesome-library.tar.gz
- Import your library into
src/app/app.module.ts, and test your library functionality somehow.
npm run compile:aot && npm run prodserver
- Go to
http://localhost:8088to see the results