Make an Angular Library

If you have the craving for an easy-peasy-hands-on-tutorial on how to setup your own library — this is everything you need to know.

What is a library?

A library is a project/package that can be used inside an application as a dependency or module. The library can be used over and over again inside an application, but it is a separate “mini-application” with its own setup of stylesheets and services.
A library can be exported to https://www.npmjs.com/ and used by others or be used with direct import as a module in app.module.ts.

When do I need it?

A library comes in handy when you need to use a specific feature over and over again. Of course you can re-use a component inside an application, but what if you need that component in another application? In those cases you might face some troubles with service logic and styles. A library is an own module, containing its own features and logic.

How do I start?

A library is not a stand-alone application. It need to be inside a regular Angular application to work, so we need to start a new project.
If you already have a project — go to “Make a new library”.

ng new my-project

And change directory to the project root-folder:

cd my-project

Make a library

Inside the root-folder, you can now generate a library:

ng g library my-library

You will now have the folders projects/my-library.

You will find your developing files inside “projects”-folder

Inside the projects-folder are all the files you need to start a library. It is like a mini version of an Angular project with its on src-folder, package.json and other stuff.

How do I set things up?

First you must let Angular know that there is a new library. To do that you need to build it:

ng build my-library

Now you have a build version of the library. The “problem” with this, is that you need to do a new build every time you have done a new change. To automatically see the updated changes, add a --watch to the build command:

ng build my-library --watch

The ng build will now generate a new folder called dist/my-library and in this folder the final (dist = distributed ) library will be held.

 — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — 
Built Angular Package
 — from: /Volumes/Macintosh — data/my-project/projects/my-library
 — to: /Volumes/Macintosh — data/my-project/dist/my-library
 — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — 

Built folder is found inside “dist”

You will also have a reference path in the tsconfig.json, refering to the dist-folder.

"paths": {
  "my-library": ["dist/my-library"]
},

After the library has been built, start the applications server.

ng serve

How do I develop the library?

You develop the library in projectsfolder, but you use the built library from dist folder in you application.
You can then copy-and-paste the build folder into a different application, if you want to.
Don’t forget to re-build the library after each changes, otherwise it won’t show up in the application.

ng build my-library
or
ng build my-library --watch

How do I use the library in my application?

Go into your root app.module.ts import your library inside imports.
Use add imports from dist/my-library as path to your folder.

The name of the module is found in:
projects/my-library/src/lib/my-library.module.ts

And inside that file take the exported name:

export class MyLibraryModule { }

Note: It is the Module path from dist that should be imported, not the Components path from projects.

import { MyLibraryModule } from 'dist/my-library';
imports: [
...
  MyLibraryModule
]

Inside the projects/my-library/src/lib/my-library.component.ts, there is a key called selector. That is the name used as a tag name when you add the library to another component, just as you would when you’re using a component in the main application.
The value in the selector can be changed. The default value have a prefix of lib-, like lib-my-library.
(Don’t forget to run ng build after changing the selector)

If you change the selector to my-library:

selector: 'my-library'

You can now be used everywhere in the application with the same name:

<div>
  <my-library></my-library>
</div>

This is conventional to do when you later on want to use it in other applications — to have a smashing nice library name!

Run the server with ng serve and look at your masterpiece!

And the result should read: “ my-library works!”

Wow! I’d buy that for a dollar!

Wrap it up

That’s pretty much it. Developing your own library isn’t hard. The issues I had the first time, was about forgetting to do a new build after each change and link to the correct folder. Otherwise it was straightforward and not so difficult.

Good luck and happy coding!