This article has been upgraded to the angular version
6.1.0after previously being written for the prerelease version
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.
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:
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
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
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
Make sure to also remove their references in the
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 classtherefore later we can simply create a service by using
SomeService extends NgxCliLibDemoCrud
- We have to set
endPointand define some logic though which we will process any given data (
- The rest is just all CRUD relevant fuctions called via the
HttpClientpassing 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
- generating a new service using the angular-cli (
ng generate service JsonTest)
- providing it in our
- setting it up:
- calling the newly created service, e.g. as
app.component.tsfor testing purposes only — of course:
- fire everything up (
ng serve) and check things out locally (
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
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.
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.
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.