guide angular library - devonfw/devon4ng GitHub Wiki
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.
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.
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.
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=falseThis 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.
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.
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.
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.
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"
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.
npm packyarn pack-
Add a
README.mdand LICENSE file. The text insideREADME.mdwill be used in you npm package web page as documentation. -
run
npm adduserif you do not have a npm account to create it, otherwise runnpm loginand introduce your credentials. -
run
npm publishinsidedist/"library-name"folder. -
Check that the library is published: https://npmjs.com/package/library-name
In this step we are going to install/add the library on other projects.
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.tgzgenerated in Packing the library. -
Option 2: run
npm install "library-name"to install it from npm repository.
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.tgzgenerated in Packing the library. -
Option 2: run
yarn add "library-name"to install it from npm repository.
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:
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.
This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).
