Yeoman generator to create a standalone Angular library in seconds.
If you want to create an Angular library with directives, services and/or pipes, then this generator is just what you need.
This generator aligns with the official Angular Package Format and automatically generates a Flat ES Module, a single metadata.json and type definitions to make your library ready for AOT compilation by the consuming Angular application.
Watch Jason Aden's talk to learn more about the Angular Package Format.
More specifically, this generator:
- creates and configures
package.json
for the development of your library - creates and configures a second
package.json
for the distribution of your library - creates and configures
tsconfig.json
for your editor during development - creates and configures
tslint.json
for linting purposes - creates and configures
.gitignore
,.npmignore
and.travis.yml
- creates the main library file, a sample directive, a sample component, a sample service and a sample pipe
- configures tslint for you with codelyzer support
- creates and configures build scripts to generate a Flat ES Module (FESM), type definitions and metadata files for your library to make it ready for AOT compilation
- inlines templates automatically for you so you can use external HTML templates
- inlines styles automatically for you so you can use external CSS templates
This generator is built for Angular version 2 and above, hence the name generator-angular2-library. If you are looking for a similar generator for AngularJS 1.x, please visit generator-angularjs-library.
First, install Yeoman and generator-angular2-library using npm (assuming you already have node.js pre-installed).
$ npm install -g yo
$ npm install -g generator-angular2-library
make a new directory and cd
into it:
$ mkdir angular-library-name
$ cd angular-library-name
and generate your new library:
$ yo angular2-library
The generator will prompt you for:
? Your full name: Jurgen Van de Moere
? Your email address: jurgen.van.de.moere@gmail.com
? Your library name (kebab case): angular-library-name
? Git repository url: https://github.com/jvandemo/angular2-library-name
and create the following files for you:
.
├── README.MD
├── build.sh
├── package.json
├── src
│ ├── index.ts
│ ├── package.json
│ ├── sample.component.ts
│ ├── sample.directive.ts
│ ├── sample.pipe.ts
│ ├── sample.service.ts
│ └── tsconfig.es5.json
├── tsconfig.json
└── tslint.json
You can then add or edit *.ts
files in the src/
directory and run:
$ npm run build
to automatically create all *.js
, *.d.ts
and *.metadata.json
files in the dist/
directory.
The generates creates 2 TypeScript config files:
tsconfig.json
is used to configure your editor during development and is not used for building your librarysrc/tsconfig.es5.json
is used by the Angular compiler to build the files in thedist
directory when you runnpm run build
Everything comes pre-configured with tslint and codelyzer support. To lint your code:
$ npm run lint
From the root of your library directory, run:
$ npm run build
This will generate a dist
directory with:
- a
package.json
file specifically for distribution with Angular listed in thepeerDependencies
sample-library.js
: a Flat ES Module (FESM) file that contains all your library code in a single file*.d.ts
: type definitions for you librarysample-library.metadata.json
: metadata for your library to support AOT compilation
From the root of your library directory, run:
$ npm run docs:build
This will generate a docs
directory with all documentation of your library.
To serve your documentation, run:
$ npm run docs:serve
and navigate your browser to http://localhost:8080
.
To automatically rebuild your documentation every time a file in the src
directory changes, run:
$ npm run docs:watch
For more features, check out the compodoc website.
To publish your library to NPM, first generate the dist
directory:
$ npm run build
and then publish the contents of the dist
directory to NPM:
$ npm publish dist
Once you have published your library to the NPM registry, you can import it in any Angular application by first installing it using NPM:
$ npm install sample-library # use the name you used to publish to npm
and then importing your library in your Angular AppModule
(or whatever module you wish to import your library into):
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
// Import your library
import { SampleModule } from 'sample-library';
@NgModule({
declarations: [
AppComponent
],
imports: [
BrowserModule,
// Specify your library as an import
SampleModule
],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule { }
Once your shared library is imported, you can use its components, directives and pipes in your Angular application templates:
<!-- app.component.html -->
<h1>{{ title }}</h1>
<sample-component>
This component is part of the shared library and will now work as expected.
</sample-component>
and if you need to access a service from your shared library, you can inject it using Dependency Injection:
import { Component } from '@angular/core';
// Import the shared service
import { SampleService } from 'sample-library';
@Component({
template: 'Injecting a service from the shared library'
})
export class HomeComponent {
// Inject the service using Angular DI
constructor(private sampleService: SampleService){
}
}
To learn more about Angular Dependency Injection, check out the Official Angular Documentation.
To consume your library before you publish it to npm, you can follow the following steps:
- Create your library:
$ yo angular2-library
Let's assume you name your library sample-library
.
- Navigate to the
sample-library
directory:
$ cd sample-library
- Compile your library files:
$ npm run build
- From the
sample-library/dist
directory, create a symlink in the global node_modules directory to thedist
directory of your library:
$ cd dist
$ npm link
- Create a new Angular app. Let's assume you use angular-cli:
$ cd /your-projects-path
$ ng new my-app
- Navigate to the
my-app
directory:
$ cd my-app
- From the
my-app
directory, link the globalsample-library
directory to node_modules of themy-app
directory:
$ npm link sample-library
- Import
SampleModule
in your Angular application:
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
// Import your library
import { SampleModule } from 'sample-library';
@NgModule({
declarations: [
AppComponent
],
imports: [
BrowserModule,
// Specify your library as an import
SampleModule
],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule { }
- Once your shared library is imported, you can use its components, directives and pipes in your Angular application templates:
<!-- app.component.html -->
<h1>{{ title }}</h1>
<sample-component>
This component is part of the shared library and will now work as expected.
</sample-component>
and if you need to access a service from your shared library, you can inject it using Dependency Injection:
import { Component } from '@angular/core';
// Import the shared service
import { SampleService } from 'sample-library';
@Component({
template: 'Injecting a service from the shared library'
})
export class HomeComponent {
// Inject the service using Angular DI
constructor(private sampleService: SampleService){
}
}
- When you make a change to your library, recompile your library files again from your
sample-library
directory:
$ npm run build
- If you want to automatically recompile the library files when a file in
src
changes, run
$ npm run build:watch
First update the package name in src/package.json
:
"name": "@scope/library-name"
and then also update flatModuleId
in src/tsconfig.es5.json
accordingly:
"flatModuleId": "@scope/library-name"
See #75 for more information.
If you experience issues (#72) or want to avoid constant recompilation of your library during development, you can also npm link src
instead of npm link dist
in step 4 of the process above.
This will let you consume the TypeScript code directly from the src
directory of your library instead of the generated bundle from the dist
directory. This increases development speed if you are testing your library in a local Angular application, but remember to test the generated bundle using npm link dist
after you finish writing your code, to ensure that your generated bundle is working as expected before you publish your library to NPM.
- Create process for running unit tests
Please report bugs and issues here.
To run the generator unit tests:
$ npm run test
MIT © Jurgen Van de Moere
- Added convenience scripts for generating documentation
- Added compodoc for generating documentation (#76)
- Removed comments from TypeScript config files to allow JSON validity checks
- Added Gulp for support on Mac, Linux and Windows (Credits to Carlos Roso)
- Added template inlining (Credits to Filipe Silva)
- Added style inlining (Credits to Filipe Silva)
- Updated TypeScript files in gitignore
- Added build:watch script
- Added dist folder to gitignore
- Remove prepublish script
- Update build process
- Add support for AOT compilation
- Update to Angular 4
- Update to Yeoman 1.x
- Ignore files generated by ngc in .gitignore
- Remove obsolete files in package.json
- Add README.md to package.json so NPM registry can display it
- Update devDependencies
- Update to latest tslint and codelyzer
- Update TypeScript version to fix #41
- Fix eslint errors
- Remove duplicate dependency
- Suggest better default library name
- Add support for AOT compilation
- Update Angular 2 references to just Angular
- Replace typings with @types (#29)
- Remove default keyword when exporting module to fix #23
- Updated version of Codelyzer
- Updated selector of sample component to kebab case to fix #21
- Fixed unit tests
- Fixed
README.md
example code
- Fixed
tsconfig.json
files
- Added support for
NgModule
- Updated dependencies in package.json to Angular 2 final
- Updated templates to Angular 2.0.0 RC3 syntax
- Updated with file structure using
src
anddist
directory
- Updated templates to Angular 2.0.0 RC1 syntax
- Added codelyzer support
- Added tslint support
- Added typings support
- BREAKING CHANGE: Updated to support Angular 2.0.0-rc.1
- Updated dependency versions
- Added
browser.d.ts
to files intsconfig.json
instead of using tripleslash (see #9)
- Added reference to Angular typings
- Removed explicit RxJS dependency
- Updated to Angular 2 beta
- Added documentation
- Added support for
PROVIDERS
,DIRECTIVES
andPIPES
- Added documentation
- Added boilerplate scaffolding
- Initial version