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

Yaaay!

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.

How to build a library for Angular apps?

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:

Double check the SASS structure is correct

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

Are you feeling it??

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:

You can check it on https://airbnb.io/react-dates/

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

Doesn’t looks cool as storybook, but it makes your code more organized

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

Look how pretty is it!

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:

Testing Angular faster with Jest - Xfive

• 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