Easily create and publish your next Angular library with Yeoman via generator-ngx-library
Let’s say it guys, Angular is one of the best JS framework out there! You are probably and justifiably using it right now to write your web applications and/or the ones to come (if not 😱, you should really consider it).
You may even be thinking about writing your very own, either from scratch, or by extracting a shared module you’ve created as part of that big application you’ve been working on.
In both case, you quickly discover that the process of releasing an Angular library the right way, is not that simple. There is so many things to think of, like:
- Inlining the external styles and templates in your components
- Writing and compiling your library so that it is compatible for Ahead Of Time (AOT) compilation
- Distributing a package as as small as possible, to reduce its footprint for final consumers
- Distributing a package that plays well with TypeScript by allowing auto-completion and compile-time type checking
- Bundling your library to allow most users to consume it via SystemJS or Webpack
And the list goes on.
Maybe you’ve already done all that for that one library you published last month. But now, you are working on a new awesome library to release. Though it is totally different from the previous one, still, the building/testing chain around is EXACTLY the same, or very very close. And you are tired of copying/renaming the files over and over again, from one project to the other.
This is what led to the creation of generator-ngx-library!
What is it?
generator-ngx-library is a Yeoman generator that aims to ease the painful/cumbersome process of creating and releasing an Angular library, so that you can really focus on the most important: writing the actual library!
Beyond generating the minimum code to get you started quickly, it provides you with a full build and testing setup ready-to-use, along with integration with popular tools to improve your workflow, code quality and maintenance.
These are some of the main features covered by the generator:
- Ahead Of Time(AOT) Compilation, Flattened ES Modules(FESM), [Minified] UMD Bundles, Closure Compiler support (follows Angular Package Format)
- Code Linting based on codelyzer rules
- Styles and Templates Inlining in components
- SASS/SCSS to CSS compilation
- Integrated demo app built with angular-cli and ng-bootstrap
- Project Documentation built with compodoc and published along with demo app 📚
- Continuous Integration with Travis CI
- Testing Environment with Karma and Webpack
- Code Coverage with Coveralls.io
- Real-time Monitoring and Automatic Updates of npm dependencies with Greenkeeper 🌴
- Publication to npm registry
- Releasing to Github
You see? the tool really takes care of everything for you!
How to install ?
$ npm install -g yo gulp-cli @angular/cli
// or via Yarn
$ yarn add global yo gulp-cli @angular/cli
Then, simply install the generator:
$ npm install -g generator-ngx-library
// or via Yarn
$ yarn add global generator-ngx-library
How to create your library ?
Very simple. Create the root folder of your library, move into it and run:
Answer the questions you are prompted to:
This will generate a fully git-ready project containing your library, and based on the exact options and answers you provided during the initialization.
How to publish your library?
The big time has arrived! Your library is done being written and fully tested. It is now time to publish it to the world.
gulp release --version=[major|minor|patch]
Upon running this command, the tool will perform a serie of pre-release checks, to make sure that your library is indeed ready to be published:
If pre-release checks failed, the whole process is aborted. Otherwise, Congratulations! You’ve just published your library on NPM and Github!
This was just a quick introduction about what the generator is capable of. For more detailed information, list of available options, recipes, please visit the project’s page on Github.
Found an issue, thought about a nice feature that could be added, please file an issue. Contributions are welcome!
Further information about the resources that helped me designing the generator, please read the following articles: