guide angular library

Table of Contents

• Angular Library
  • Whats a library?
  • How to build a library
    • 1. Creating an empty application
    • 2. Generating a library
    • 3. Modifying our library
    • 4. Exporting the generated things
    • 5. Building our library
    • 6. Packing the library
    • 7. Publishing to npm repository (optional)
    • 8. Installing our library in other projects
    • 9. Using the library
    • devon4ng libraries

Angular Library

Angular CLI provides us with methods that allow the creation of a library. After that, using a packet manager (either npm or yarn) the library can be build and packed which will allow later to install/publish it.

Whats a library?

From wikipedia: a library is a collection of non-volatile resources used by computer programs, often for software development. These may include configuration data, documentation, help data, message templates, pre-written code and subroutines, classes, values or type specifications.

How to build a library

In this section, a library is going to be build step by step. Please note, we will be explaining the steps using both Angular CLI and Nx CLI. You are free to choose either one for your development.

1. Creating an empty application

First, using Angular CLI we are going to generate a empty application which will be later filled with the generated library. In order to do so, Angular CLI allows us to add to ng new "application-name" an option (--create-application). This option is going to tell Angular CLI not to create the initial app project. This is convenient since a library is going to be generated in later steps. Using this command ng new "application-name" --create-application=false an empty project with the name wanted is created.

ng new "application-name" --create-application=false

This step is much more easier and straight-forward when using Nx. Nx allows us to work in a monorepo workspace, where you can develop a project as an application, or a library, or a tool. You can follow this guide to get started with Nx. The command for generating a library in Nx is nx generate @nrwl/angular:library library-name --publishable --importPath=library-name. This will create an empty angular application which we can modify and publish as a library.

2. Generating a library

After generating an empty application, a library is going to be generated. Inside the folder of the project, the Angular CLI command ng generate library "library-name" is going to generate the library as a project (projects/"library-name"). As an addition, the option --prefix="library-prefix-wanted" allows us to switch the default prefix that Angular generated with (lib). Using the option to change the prefix the command will look like this ng generate library "library-name" --prefix="library-prefix-wanted".

ng generate library "library-name" --prefix="library-prefix-wanted"

If you are using Nx, this step is not needed as it is already covered in step 1. In this case, the library project will be generated in the libs folder of a Nx workspace.

3. Modifying our library

In the last step we generated a library. This automatically generates a module,service and a component inside projects/"library-name" that we can modify adding new methods, components etc that we want to use in other projects. We can generate other elements, using the usual Angular CLI generate commands adding the option --project="library-name", this will allow to generate elements within our project . An example of this is: ng generate service "name" --project="library-name".

ng generate "element" "name" --project="library-name"

You can use the same command as above in a Nx workspace.

4. Exporting the generated things

Inside the library (projects/"library-name) there’s a public_api.ts which is the file that exports the elements inside the library. (The file is named as index.ts in an Nx workspace). In case we generated other things, this file needs to be modified adding the extra exports with the generated elements. In addition, changing the library version is possible in the file package.json.

5. Building our library

Once we added the necessary exports, in order to use the library in other applications, we need to build the library. The command ng build "library-name" is going to build the library, generating the necessary files in "project-name"/dist/"library-name".

ng build "library-name"

You can use the same command in Nx as well. Only the path for the generated files will be slightly different: "project-name"/dist/libs/"library-name"

6. Packing the library

In this step we are going to pack the build library. In order to do so, we need to go inside dist/"library-name" (or dist/libs/"library-name") and then run either npm pack or yarn pack to generate a "library-name-version.tgz" file.

Listing 1. Packing using npm

npm pack

Listing 2. Packing using yarn

yarn pack

7. Publishing to npm repository (optional)

• Add a README.md and LICENSE file. The text inside README.md will be used in you npm package web page as documentation.

• run npm adduser if you do not have a npm account to create it, otherwise run npm login and introduce your credentials.

• run npm publish inside dist/"library-name" folder.

• Check that the library is published: https://npmjs.com/package/library-name

8. Installing our library in other projects

In this step we are going to install/add the library on other projects.

npm

In order to add the library in other applications, there are two ways:

• Option 1: From inside the application where the library is going to get used, using the command npm install "path-to-tgz"/"library-name-version.tgz" allows us to install the .tgz generated in Packing the library.

• Option 2: run npm install "library-name" to install it from npm repository.

yarn

To add the package using yarn:

• Option 1: From inside the application where the library is going to get used, using the command yarn add "path-to-tgz"/"library-name-version.tgz" allows us to install the .tgz generated in Packing the library.

• Option 2: run yarn add "library-name" to install it from npm repository.

9. Using the library

Finally, once the library was installed with either packet manager, you can start using the elements from inside like they would be used in a normal element inside the application. Example app.component.ts:

import { Component, OnInit } from '@angular/core';
import { MyLibraryService } from 'my-library';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent implements OnInit {

  toUpper: string;

  constructor(private myLibraryService: MyLibraryService) {}
  title = 'devon4ng library test';
  ngOnInit(): void {
    this.toUpper = this.myLibraryService.firstLetterToUpper('test');
  }
}

Example app.component.html:

<!--The content below is only a placeholder and can be replaced.-->
<div style="text-align:center">
  <h1>
    Welcome to {{ title }}!
  </h1>
  <img width="300" alt="Angular Logo" src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNTAgMjUwIj4KICAgIDxwYXRoIGZpbGw9IiNERDAwMzEiIGQ9Ik0xMjUgMzBMMzEuOSA2My4ybDE0LjIgMTIzLjFMMTI1IDIzMGw3OC45LTQzLjcgMTQuMi0xMjMuMXoiIC8+CiAgICA8cGF0aCBmaWxsPSIjQzMwMDJGIiBkPSJNMTI1IDMwdjIyLjItLjFWMjMwbDc4LjktNDMuNyAxNC4yLTEyMy4xTDEyNSAzMHoiIC8+CiAgICA8cGF0aCAgZmlsbD0iI0ZGRkZGRiIgZD0iTTEyNSA1Mi4xTDY2LjggMTgyLjZoMjEuN2wxMS43LTI5LjJoNDkuNGwxMS43IDI5LjJIMTgzTDEyNSA1Mi4xem0xNyA4My4zaC0zNGwxNy00MC45IDE3IDQwLjl6IiAvPgogIDwvc3ZnPg==">
</div>
<h2>Here is my library service being used: {{toUpper}}</h2>
<lib-my-library></lib-my-library>

Example app.module.ts:

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';

import { MyLibraryModule } from 'my-library';
@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    AppRoutingModule,
    MyLibraryModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

The result from using the library:

devon4ng libraries

In devonfw/devon4ng-library you can find some useful libraries:

• Authorization module: This devon4ng Angular module adds rights-based authorization to your Angular app.

• Cache module: Use this devon4ng Angular module when you want to cache requests to server. You may configure it to store in cache only the requests you need and to set the duration you want.