Creating Library with Angular 6+: The ultimate guide
Let’s make components great again!
As you may know, the modern web development is component based to improve the re usability and fast development .
On this article I’ll try to make a summary to how do prepare a library project with Angular 6+.
Before starting this article I would recommend have some experience with Angular and Angular CLI to not get lost.
First things first
Make sure that you have updated angular-cli and generate a new project
> ng new foo-library
> cd foo-library
With the new project on hands, you will have to generate an library (you can generate multiple libraries according your project architecture)
> ng g library @foo/bar --prefix fb
Note: ng generate library
has some extra options, you can check it here
Doing that you will have a new folder /projects
, all the libraries changes should be done there.
Our first component
It’ simple like that!
> ng g c counter --project=@foo/bar
I’ll not be going very keep how you build your library it-self, you can check this article, it goes through the basics concepts.
Let’s just make simple changes in our component to make it a bit more interactive.
Friendly advice for styles
If you don’t care how to deal with potential styles issues, you can skip this
Note that Angular has view encapsulation, so when the library be published, you will not be able to change the style added from styleUrl
, there’s multiple ways that you can avoid this issue, the easier one is just deactivating the view encapsulation in your components like Angular Material does and create some mixing that generates BEM structure.
But personally I prefer to use an hybrid solution of mixing and view encapsulation, but it requires do some changes on the build process, that i’ll be explaining.
For our counter component, you can leave the styles that don’t need to be customized on counter.component.scss
, like we did. (of course, this will be different for each case)
Then you can have a mixing that will be outside from the view encapsulation, I would recommend follow some documented structure (eg Bootstrap, Material Desgin)
For example:
Doing that you will have a entry file, so you just need to import once your file. I leave this file on /src/main.scss
.
So the project that you will be using it you just need to do:
Last but not least, you need to create a custom build script to copy to avoid be copying and pasting every-time the styles.
> ng build @foo/bar && node <PATH_TO_YOUR_CUSTOM_SCRIPT>
Your dist
folder should look like this for this example:
Then you are ready to publish your component on npm! (remember to remove the private: true
from package.json
of your library project, more info on npm official website)
> cd dist/foo/bar
> npm publish
Then just be happy and install your new library on your project
> npm i @foo/bar
Wait!! It’s not over yet.
At this point you should be asking “What the well i’ll do with the application folder(./src/app)????”, then we go for the best part
A good library is not the same without the components documentations, every big framework have, why can’t we have it?
I’ve found two good libraries for that, you can use Storybook (that initially was made for React, but it kinda of works with Angular), you have something like this:
But it has some issues with refreshing the components, so you need to be re-building the components everytime (at least while I was testing it).
So I’ve found UI-Jar, it’s simple to use and you make your code self-documented
For using it, you basically needs to follow the README.md
, then in 5 min you have it up and running. But here we will modify a bit, and use it as our main application for our libraries
First you need to add it to the project
> npm install ui-jar
After that, you need to update src/tsconfig.app.json
, src/styles.scss
, src/main.ts
and src/index.html
After that we need just to update our scripts
on package.json
Note that we are using concurrently to run both tasks at the same time, you will need to install it before running
> npm i --save-dev concurrently
Now we just need to update our counter according the ui-jar markups, it will looks something like this:
So now just run the following command and see our final result!
> npm run serve
After notes
- Testing: I really recommend together with all this you use Jest as well, it’s amazing how fast is it. You can easily install following this article:
- Translations: It’s not possible to use
ng xi18n
(more info), with ng-packagr you would need to use ngx-translate and mock the tests with ngx-translate-testing - UI-Jar component reloading: There’s a issue with reloading components with UI-Jar (#47), so I’ve remove the filter on watch (may can make it a bit slower, but works as temporary solution), you can install from my fork.
> npm i -D git+https://github.com/picheli20/ui-jar.git#always-refresh