How to Build and Publish Angular Library

Photo by Robert Bye on Unsplash

Hello Readers,

In this article, you can learn How to Create an Angular Library Step by Step and Publish it. We are going to cover the following topics:

· What is Angular Library?

· Why we need a Library?

· Creating a Library

· Using a Library in local Angular Application

· Publishing Library to Local npm

· Publishing Library to Public npm Repository

What is Angular Library?

A library is a collection of components, services, directives, etc. that can be shared across different Angular projects.

More precisely, in programming, the Library is a collection of precompiled routines that a program can use.

An Angular library is an Angular project that differs from an app in that it cannot run on its own. A library must be imported and used in an angular app.

So, an Angular library is a Sharable code which provides Reusable functionality.

Why we need a Library?

Now the main question is why we need this library? Do we need this? Well yes,

Sometimes components, services, etc could apply to multiple angular projects. So to re-use this code easily across different apps, this concept of creating our Angular library was introduced.

These libraries can be used locally in your workspace, or you can publish them as npm packages to share with other projects or with other Angular developers across the globe.

So let’s get started…

Creating a Library:

With Angular CLI it’s much easier to manage the Library.

To create a library we are having a very simple command as below:

ng generate library <library-name>

But, at First, in this tutorial, we will create a normal Angular Application and then we will create a library inside this particular application and then use it here locally. After that, we will publish this library to our local npm (our local machine).

So let us create any normal angular application first:

Now inside this angular application, write the below command to create the library project:

(here, my-demo-lib is the name of our library project and this name should not be in uppercase)

As you can see above, it has created these many files for us and it has updated angular.json, package.json and tsconfig.json files of our main angular application.

Now you might be wondering that why we need an angular application to create a library project as both are different things?

So the answer is, yes it is not needed but in our case, we will first check that the library is working properly in our local angular project or not and if it works properly then only we can publish it to npm.

Okay moving on,

Open this angular application in your IDE and in solution explorer you can see it has generated a new library ‘my-demo-lib’ under the projects folder of our workspace.

Changes made inside angular.json:

It has added our library project ‘my-demo-lib’ configuration to the ‘projects’ parameter.

Changes made inside package.json:

Changes made inside tsconfig.json:

Here it stores the output path (dist) where our library should compile and stored.

Now see the directory structure of the library project my-demo-lib:

As you can see it has its package.json and other files that have their dependencies and version numbers.

Now have a look at the public-api.ts file inside the src folder.

This is the entry point for our library project. Whatever the component, Services, Directives, etc you want to expose to the outside world needs to export here. By doing this anyone can use these by importing it.

Now check this lib directory:

As you can see it has already generated the ‘my-demo-lib’ component for us. Inside the my-demo-lib.component.ts file, you can see that it has a ‘template’ in the Component decorator. This is having some text inside a paragraph tag. So by using this component, we will get to see this text on our browser!

Now, it’s time to use this library in our angular project.

Using a Library in Local Angular Application:

To use this library anywhere we first need to BUILD it. We cannot use a library without building a dist folder. So for this open your terminal and write the following command:

Syntax: ng build <library-name>

Example: ng build my-demo-lib

This command will create a dist folder and inside this folder, our compiled library is stored.

Now we can use this compiled library in any angular application.

Importing the library in Angular App:

From solution explorer open app.module.ts and import our library just like we import any other in-built library of angular:

import { MyDemoLibModule } from ‘my-demo-lib’;

and also register this module to the Imports array of this file:

And now we can use our demo component (of a library) on our app component.

app.component.html

<lib-my-demo-lib></lib-my-demo-lib>

Now run this angular app using ng serve command and check it out.

Yeah…!!! Isn’t it cool..!!

Alright, let’s add some more functionality to our library project:

From the solution, explorer opens the src folder of the library project. And inside this, we are going to generate one new component.

We will add one simple component to having Counter functionality.

ng g c CounterDemo - -project my-demo-lib

(here, CounterDemo is the name of the component and we have to pass — project

flag to indicate that in which project we want to generate this component)

Note that it has automatically updated my-demo-lib.module.ts file. But in this file, it has only declared our CounterDemo component and if we want to use this CounterDemo component outside in any angular project, we must have to add it to the ‘exports’ array inside NgModule decorator.

As well as do not forget to export it to the public-api.ts file also.

Now, on counter-demo.component.html, we will have 2 buttons: one to increment the counter value and another one to decrement the counter value by clicking on it.

counter-demo.component.html

counter-demo.component.ts

Now let’s use this counter component in our angular project.

For this, we have to create the BUILD again. So,

ng build my-demo-lib

(Note: Whenever you make any change to the library, you have to compile it again. So you need to run this build command each time)

Now at this point, we do not require to import this CounterDemo component to the app.module.ts file.

Why? Because we had already imported the entire my- demo-lib Module. And CounterDemo component is inside this module. That’s why we do not require importing it. (But you can import it if you want).

Ok, now let’s call this CounterDemo component directly to the app-component.

app.component.html

<lib-counter-demo></lib-counter-demo>

And run this angular project using ng serve,

And it works..! As you can see above Counter is showing and now click on the buttons and check the updated counter value.

Now the important benefit of using Angular Library is that when you Publish it, you can use this CounterDemo component in any other angular project too. So let’s see how to do this.

Publishing Library to Local npm:

For this, we need to build this library as an npm package and then we can publish it to the local node package manager’s registry so that we can use it in any angular projects which are in our local machine.

This means we need to follow 2 steps:

1) Create the Build

2) Create a Pack file

1) The first step is to create the build (compiled form). As we have already done this previously we can omit this step now.

2) To create a Pack file, open the Terminal and navigate up to your library folder from the dist directory and then write down a command to create the Pack file:

This will make a Pack (target) file with a name my-demo-lib-0.0.1.tgz.

Publishing has done..!! Now we can use this library in any angular application.

So let’s quickly create a brand new angular application and use this newly created library package there!

Follow the command as shown below:

ng new angularAppDemo

Now to use our library in this project, we need to copy a path of the library. (where our library is located)

So copy the absolute path of the library project with the target file name(of dist folder) from your PC’s file explorer.

Now open Terminal from angularAppDemo and write down following command with the pack file name:

This will install the library project for our angularAppDemo.

You can check the changes made inside package.json of this angular application.

As you can see it has added a local reference to the library in our current angular project.

Now let’s use our library’s CounterDemo component here.

For that, the first thing is to import this library module in app.module.ts.

And now you can use the CounterDemo component on our app.component.html just like we have done previously.

<lib-counter-demo></lib-counter-demo>

Time to run the application!

And yes you can see it is working nice..!!!

That’s all on your local machine — now is the time to make it public.

Publishing Library to Public npm Repository:

To publish the library to the public npm repository, you have to sign up for an account with npmjs.

You can create your npmjs account here:

https://www.npmjs.com/signup

Now run the below command from the terminal and provide your npm credentials when asked:

npm adduser

(Note: This is a one-time operation only and you can skip this step if you have already logged in.)

Anytime, you can also verify that you are logged in or not by using the following command:

npm whoami

Once logged in, you need to navigate up to your library directory from the dist directory. In short,

Finally, we are ready to publish our library. Remember that, we already used npm pack so we can just publish our .tgz file (Otherwise you need to run the npm pack command first)

npm publish - -access public

Then we can see the published package on npm at this URL:

https://www.npmjs.com/package/< library- name>

Now that we have created and published this library we can use it anywhere in any project by running the following command:

npm install — save <library-name>@0.0.1

(here 0.0.1 is the version number of a library, which is necessary)

Few Adjustments:

As a good programming practice, we should provide some unique name for the library.

Because our npm’s public registry will sure have many packages with these similar names. So you can follow the approach to add your npm’s username with your library name so that it can be uniquely identified and also to avoid the errors while you publish it.

For this, you can change the name parameter of the package.json file of your library project. (from projects folder)

Here this name is having npm-username/library-name value.

And now you can follow the publishing steps described above.

I hope you find this article useful. Thanks for reading!

Jinal Shah is corporate trainer on different technology like node.Js, Angular,Ionic 2, BOT Framework etc.