Building and publishing Angular libraries using Angular CLI

Photo by Giammarco Boscaro on Unsplash

This article has been upgraded to the angular version 6.1.0 after previously being written for the prerelease version 6.0.0-rc.4 .

So recently the great team behind the angular-cli published their latest version bringing a highly anticipated feature: a way to easily generate angular libraries within angular-cli. Let’s take a closer look at what this actually entails and how it works in detail, here’s how to get started.

Clean slate

You will — most likely — want to start this as a clean project, so generate a new it, no changes here, just run:

ng new ngx-cli-lib-demo

And don’t forget to change directory into you newly created project:

cd ngx-cli-lib-demo

Kickstart the library

Allright, so our project is now ready to go and we will get things rolling. To start creating you own custom library simply run the new command:

ng generate library NgxCliLibDemoCrud

Okay, this is where the magic happens. So let’s go over some of the changes which just happend:

• project/ngx-cli-lib-demo-crud — We now have a whole new folder at the root level of our angular app and it obviously holds our library files in its subdirectory. Every following bulletpoint refers to this folder as root.
• package.json — This one is crucial, here we can define a whole lot of stuff regarding our library, e.g. the version we are currently at as well as the name and required dependencies. So far you need to add your libraries by hand, just keep in mind that peerDependencies, unlike dependencies, are not automatically installed by NPM.
• ng-package.json — Everyone who has developed angular libraries using ng-packagr in the past will probably recognize a lot of these files, like this one. It defines our library’s entry point and where to output the new lib once it is compiled — no worries, everything is setup correctly right away.
• src/public_api.ts — We are getting closer, this file actually commulates all components, services and modules we actually want to make available to the outside world and sets them as APIs.
• src/lib/ — Finally, our code! Here you will find a ready-made file for a component, a service and a module, just to get you started. But yes, this is where we will actually write our code.

Besides that, some of our main files have been altered too. The angular.json file has a new config item under "projects": [...] to properly include it in your build process, the main package.json has some added dependencies, most importantly ng-packagr and the new project also got added to the tsconfig.json.

Feel free to dig deeper into the structure, I would recommend taking a closer look at ng-packagr and how it works, but this should be enough for this post as it is a brief overview. To do so I recommend starting here.

The library logic

I decided to implement a simple wrapper which provides a ready-made solution for every time we need to implement a simple CRUD service.

DISCLAIMER: This is, by any means, an example. I’m no expert on OpenSource but I still want to make clear that you should carefully think about the actually value your library will offer (if any), research if there is something even remotely similiar already published (if so, why not contribute to the existing one) and make sure you want to give somewhat of a future support to what you are making.

Think, research and support — then (maybe) publish.

To honor this approach to open source, we will make a small change to our library’s package.json. Open it up and add "private": true it then should look like this:

Since we are building a service we can ignore the component files, remove the following under projects/ngx-cli-lib-demo-crud/src/lib/:

• ngx-cli-lib-demo-crud.component.ts
• ngx-cli-lib-demo-crud.component.spec.ts
• ngx-cli-lib-demo-crud.module.ts

Make sure to also remove their references in the public_api.ts file.

Cheap talk, let’s code

Okay, so let’s implement our crazy advanced logic for our service. Look at the code, I’ll explain briefly what it does afterwards:

So here is what’s happening:

• This is an abstract class therefore later we can simply create a service by using SomeService extends NgxCliLibDemoCrud
• We have to set baseUrl , endPoint and define some logic though which we will process any given data (parseData).
• The rest is just all CRUD relevant fuctions called via the HttpClient passing data back and forth.

To be honest, if you are struggeling to understand what is happening here you you’re happily invited to code along with the examples but I recommend learning a bit more about the angular basics before going deep into building a library. The angular docs and it’s tutorials might be a good place to start. That being said. Let’s move on.

Luckily, since we also have a proper angular app all set up, we can easily implement our new service by:

• importing the HttpClientModule in our app.module.ts
• generating a new service using the angular-cli (ng generate service JsonTest)
• providing it in our app.module.ts
• setting it up:

• calling the newly created service, e.g. as OnInit in our app.component.ts for testing purposes only — of course:

• fire everything up (ng serve) and check things out locally (http://localhost:4200/)

You should now be able to see the GET call, in my case, logged in the console. Yay! Everything works just fine. So let’s ship it, huh?

Publish your library

Yes, we can. And it’s pretty simple too. Just remove the private flag from the package.json and run ng build NgxCliLibDemoCrud --prod. Everything you now have to do is change directory into dist/ngx-cli-lib-demo-crud, npm login into your account and npm publish your new library!

Your done now! Of course there are plenty of settings and meta data you not only can but honestly should author to provide a good and usable library, but this is more of a short guide to get yourself familiar with new feature of the Angular CLI.

Summary

As someone who works with angular on a daily basis I do have a ton of smaller and bigger snippets which I always wanted to distrubute properly. Even though I stressed about not publishing everything you think is helpful doesn’t mean you can’t setup you own private npm registry with all the helpful components and services you’d like to have at your disposal.

I hope this small overview provided you with just enough information to get your libraries up and running. Keep in mind that for now this is still a pre-release — some things might change.

The angular-cli team did a great job integrating it so far and I can’t wait for it to become a final release. Huge thanks to them and also to ng-packagr.

If you need help, more information or just want to chat, hit me up via twitter @faxemaxee. Happy to get your feedback!

You can also find the whole project on github: https://github.com/faxemaxee/ngx-cli-lib-demo.