{"id":27750,"date":"2020-01-08T00:00:00","date_gmt":"2020-01-07T23:00:00","guid":{"rendered":"https:\/\/blexin.com\/creare-librerie-di-componenti-angular\/"},"modified":"2021-05-20T18:44:46","modified_gmt":"2021-05-20T16:44:46","slug":"creating-angular-components-libraries","status":"publish","type":"post","link":"https:\/\/blexin.com\/en\/blog-en\/creating-angular-components-libraries\/","title":{"rendered":"Creating Angular components libraries"},"content":{"rendered":"\n
\"\"<\/figure>\n\n\n\n

It often happens we need to solve a problem already solved in a previous project using a simple copy and paste of the code. This is a fast and easy solution, but it may cause secondary effects, the worst of whom is the discovery of a bug that needs to be corrected in all projects where we passed the code. What if I want to add new functionality? Should I propagate it all over?<\/p>\n\n\n\n

In all Angular projects I worked on, it was always necessary to create a component able to pick up data and show them in table format. Why don\u2019t we make this component usable for more than one project? Angular gives us this opportunity with Angular Library<\/strong>. In my previous article<\/a>, I showed you how to create a component able to display data in table format and that allows the drag and drop of columns: let\u2019s make this component reusable in all our projects with a library!<\/p>\n\n\n\n

From the Angular CLI<\/strong> we launch following commands:<\/p>\n\n\n\n

ng new BlexinLibrary<\/code><\/p>\n\n\n\n

Regarding the creation of a library, the official Angular documentation indicates to set the flag --create-application<\/code> to false to indicate to the CLI it does not have to create an initial application but only an empty workspace. This is not the solution I choose, nor the one I prefer because it makes it difficult to make the debug of the library.
I suggest you create a classical Angular application working as a host and develop the library inside it so that you can test it before the release. In the project root folder, let\u2019s launch the command to create a library:<\/p>\n\n\n\n

ng generate library DataTable<\/code><\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Note that the Angular CLI created a project folder; inside it, we can find a folder with the name of the library (Data Table). In the sub-folder data-table\/src, we find a folder lib<\/em>, which contains files that compose the project (components, services, modules, etc.), together with a file public-api.ts that declares what we want to make available inside our library.<\/p>\n\n\n

\n\/*\n* Public API Surface of data-table\n*\/\n  \nexport * from '.\/lib\/data-table.service';\nexport * from '.\/lib\/data-table.component';\nexport * from '.\/lib\/data-table.module';\n<\/pre><\/div>\n\n\n
We find out that in the library, a component, a service, and a module have already been created. The configuration file of the whole workspace, angular.json<\/strong>, is updated with a new library<\/strong>-type project, which has the name we choose during the creation of the library.<\/p>\n\n\n
\n{\n\u00a0"$schema": ".\/node_modules\/@angular\/cli\/lib\/config\/schema.json",\n\u00a0"version": 1,\n\u00a0"newProjectRoot": "projects",\n\u00a0"projects": {\n\u00a0\u00a0\u00a0"BlexinLibrary": {\n\u00a0\u00a0\u00a0\u00a0\u00a0"root": "",\n\u00a0\u00a0\u00a0\u00a0\u00a0"sourceRoot": "src",\n\u00a0\u00a0\u00a0\u00a0\u00a0"projectType": "application",\n\u00a0\u00a0\u00a0\u00a0\u00a0"prefix": "app",\n\u00a0\u00a0\u00a0\u00a0\u00a0...\n\u00a0\u00a0\u00a0},\n\u00a0\u00a0\u00a0"BlexinLibrary-e2e": {\n\u00a0\u00a0\u00a0\u00a0\u00a0"root": "e2e\/",\n\u00a0\u00a0\u00a0\u00a0\u00a0"projectType": "application",\n\u00a0\u00a0\u00a0\u00a0\u00a0"prefix": "",\n\u00a0\u00a0\u00a0\u00a0\u00a0...\n\u00a0\u00a0\u00a0},\n\u00a0\u00a0\u00a0"DataTable": {\n\u00a0\u00a0\u00a0\u00a0\u00a0"root": "projects\/data-table",\n\u00a0\u00a0\u00a0\u00a0\u00a0"sourceRoot": "projects\/data-table\/src",\n\u00a0\u00a0\u00a0\u00a0\u00a0"projectType": "library",\n\u00a0\u00a0\u00a0\u00a0\u00a0"prefix": "lib",\n\u00a0\u00a0\u00a0\u00a0\u00a0"architect": {\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0"build": {\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0"builder": "@angular-devkit\/build-ng-packagr:build",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0"options": {\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0"tsConfig": "projects\/data-table\/tsconfig.lib.json",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0"project": "projects\/data-table\/ng-package.json"\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0}\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0},\n<\/pre><\/div>\n\n\n
Now we can proceed with writing the code as in a standard Angular project. Taking the cue from my previous article<\/a>, we delete the file that created the CLI and leave the data-table.component.ts<\/strong><\/em> and the data-table.module.ts<\/strong><\/em>, and we move on to the construction of the component.<\/p>\n\n\n\n
In the previous article, the table was not an independent component, but it was part of the app.component: therefore, we need to extract the component data-table from the app.component.
Looking at the template, we find that the data-table basically operates on two data structures: columns<\/strong> and rows<\/strong>. Both these data structures must be supplied from library users, becoming our Input<\/strong>. The .ts file of our component will be:<\/p>\n\n\n
\nimport { Component, Input } from '@angular\/core';\n  \n@Component({\n selector: 'blx-data-table',\n templateUrl: '.\/data-table.component.html',\n styleUrls: ['.\/data-table.component.css']\n})\nexport class DataTableComponent {\n @Input() columns: string[];\n @Input() rows: any[];\n  \n constructor() { }\n}\n<\/pre><\/div>\n\n\n
We modify the selector from lib-DataTable<\/strong> to blx-data-table<\/strong>, and we modify the prefix in the file tslint.json:<\/p>\n\n\n
\n{\n\u00a0"extends": "..\/..\/tslint.json",\n\u00a0"rules": {\n\u00a0\u00a0\u00a0"directive-selector": [\n\u00a0\u00a0\u00a0\u00a0\u00a0true,\n\u00a0\u00a0\u00a0\u00a0\u00a0"attribute",\n\u00a0\u00a0\u00a0\u00a0\u00a0"blx",\n\u00a0\u00a0\u00a0\u00a0\u00a0"camelCase"\n\u00a0\u00a0\u00a0],\n\u00a0\u00a0\u00a0"component-selector": [\n\u00a0\u00a0\u00a0\u00a0\u00a0true,\n\u00a0\u00a0\u00a0\u00a0\u00a0"element",\n\u00a0\u00a0\u00a0\u00a0\u00a0"blx",\n\u00a0\u00a0\u00a0\u00a0\u00a0"kebab-case"\n\u00a0\u00a0\u00a0]\n\u00a0}\n}\n<\/pre><\/div>\n\n\n
You can see below the template of our component:<\/p>\n\n\n
\n<div class="p-5 m-5">\n\u00a0<div class="p-5 m-5">\n\u00a0<div class="table-responsive table-container">\n\u00a0\u00a0\u00a0<table class="table">\n\u00a0\u00a0\u00a0\u00a0\u00a0<thead class="thead-dark">\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<tr dragula="table_columns" [(dragulaModel)]="columns">\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<th *ngFor="let column of columns">\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{{column}}\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/th>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/tr>\n\u00a0\u00a0\u00a0\u00a0\u00a0<\/thead>\n\u00a0\u00a0\u00a0\u00a0\u00a0<tbody>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<tr *ngFor="let row of rows">\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<td *ngFor="let column of columns">\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{{row[column]}}\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/td>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/tr>\n\u00a0\u00a0\u00a0\u00a0\u00a0<\/tbody>\n\u00a0\u00a0\u00a0<\/table>\n\u00a0<\/div>\n<\/div>\n<\/pre><\/div>\n\n\n
The external library we are using for the drag&drop needs some CSS classes to show the desired effect. In the previous project, I put these classes in the style.css<\/strong>. Now I don\u2019t want anyone importing the library to have to worry about adding such classes to his\/her project: they must be present in the library.
We include them in the file data-table.component.css<\/strong>.<\/p>\n\n\n\n
As I wrote, the file public_api.ts<\/strong> allows us to define what our users will see in the library. We must modify it to adjust it to the previously made service cancellation.<\/p>\n\n\n
\nexport * from '.\/lib\/data-table.component';\nexport * from '.\/lib\/data-table.module';\n<\/pre><\/div>\n\n\n
The component data-table<\/strong> requires some external dependencies: ng2-dragula<\/code> (drag&drop management) and bootstrap<\/code> (CSS classes). We need to inform those who install the library that, to guarantee the right functioning, the addition of these dependencies to their project is needed. We modify then the file package.json<\/strong> in the data-table folder, adding to it the section peerDependencies<\/strong><\/em>.<\/p>\n\n\n
\n{\n\u00a0"name": "data-table",\n\u00a0"version": "0.0.1",\n\u00a0"peerDependencies": {\n\u00a0\u00a0\u00a0"@angular\/common": "^7.0.0",\n\u00a0\u00a0\u00a0"@angular\/core": "^7.0.0",\n\u00a0\u00a0\u00a0"bootstrap": "^4.3.1",\n\u00a0\u00a0\u00a0"ng2-dragula": "^2.1.1"\n\u00a0}\n}\n<\/pre><\/div>\n\n\n
Before the publication, we must be sure that everything is working fine. The initial choice to create an Angular project and not an empty workspace now gives us a significant advantage: to test the library, we only need to import its module in our app.module and use the component through the selector. This is how our app.component.html<\/strong> becomes:<\/p>\n\n\n
\n<div style="text-align:center">\n\u00a0<h1>\n\u00a0\u00a0\u00a0Welcome to {{ title }}!\n\u00a0<\/h1>\n<\/div>\n<blx-data-table [columns]="columns" [rows]="rows"><\/blx-data-table>\n<\/pre><\/div>\n\n\n
where columns and rows are defined in app.component.ts<\/strong><\/em> and then passed in input to the data-table<\/strong>. Before we can launch our application, we need to install both dependencies in our library (with instructions npm install ng2-dragula<\/code> and npm install bootstrap<\/code>), add \"node_modules\/bootstrap\/dist\/css\/bootstrap.css\"<\/code> among the styles of our angular.json<\/strong> and in the end add (window as any).global = window;<\/code> in the polyfills.ts<\/strong> file, as suggested in the Dragula documentation.<\/p>\n\n\n\n
We launch then the application with ng serve<\/code><\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
As we verified that everything is working fine, we can distribute it. Let\u2019s compile the library and add the name of the library to the build command:<\/p>\n\n\n\n
ng build DataTable<\/code><\/p>\n\n\n\n
When we finish compiling, the library will be available in the dist folder.<\/p>\n\n\n\n
How to use the newly created library<\/h2>\n\n\n\n
We have two options: we can import it in a new project collecting it form its dist folder, or we can make it available together with its updates using the same ecosystem chosen by Angular: npm.
Let\u2019s create a new Angular project:<\/p>\n\n\n\n
ng new demo-with-lib<\/code><\/p>\n\n\n\n
Inside the structure of the just created project, we create a new lib folder, where we copy the folder containing the result of the build of the library. I can then install it with the command:<\/p>\n\n\n\n
npm i .\/libs\/data-table<\/code><\/p>\n\n\n\n
Now we also add the dependencies required for the right functioning and import the module DataTableModule<\/code> in the app.module.ts<\/em> to use the exposed component.<\/p>\n\n\n
\nimport { BrowserModule } from '@angular\/platform-browser';\nimport { NgModule } from '@angular\/core';\nimport { DataTableModule } from 'data-table';\nimport { AppComponent } from '.\/app.component';\n\u00a0\u00a0\n@NgModule({\n\u00a0declarations: [\n\u00a0\u00a0\u00a0AppComponent\n\u00a0],\n\u00a0imports: [\n\u00a0\u00a0\u00a0BrowserModule,\n\u00a0\u00a0\u00a0DataTableModule\n\u00a0],\n\u00a0providers: [],\n\u00a0bootstrap: [AppComponent]\n})\nexport class AppModule { }\n<\/pre><\/div>\n\n\n
We position the component with the proper tag blx-data-table<\/code> in the app.component.ts<\/em> providing expected inputs:<\/p>\n\n\n
\n<div class="text-center">\n\u00a0<h1>\n\u00a0\u00a0\u00a0Welcome to {{ title }}!\n\u00a0<\/h1>\n<\/div>\n<blx-data-table [columns]="columns" [rows]="rows"> <\/blx-data-table>\n<\/pre><\/div>\n\n\n
Let\u2019s launch the application and verify that is working fine.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
We have made progress: we can reuse the component everywhere we want. Actually, we have used the copy and paste again: not of the source code, but of the library distribution folder. What if we want other members of a team to use the library, providing them with a simple tool to follow its updates? What if I want to make it public, that\u2019s to say permit anybody all over the world to install it via npm?<\/p>\n\n\n\n
At the address https:\/\/docs.npmjs.com\/creating-and-publishing-private-packages <\/a>, is available an official tutorial to publish a package on a public npm registry. We will follow a different path offered by GitHub over the past few months.<\/p>\n\n\n\n
GitHub gives the chance to create our own repository thanks to GitHub Packages<\/strong>, where you can publish and distribute your library in private or public mode.<\/p>\n\n\n\n
How to publish on GitHub Packages<\/h2>\n\n\n\n
In order to publish, install, and eventually delete a package from GitHub Packages, an access token is required. There are two ways to obtain one: using the personal Access Token with your username to authenticate on GitHub or using a GITHUB_TOKEN to authenticate on GitHub Actions.<\/p>\n\n\n\n
I choose the personal access token. We need then to modify the file ~\/.npmrc<\/strong><\/em> and insert the following line:<\/p>\n\n\n\n
\/\/npm.pkg.github.com\/:_authToken=TOKEN<\/code><\/p>\n\n\n\n
and substitute \u201cTOKEN\u201d with your own token.<\/p>\n\n\n\n
Now we need to create the file .npmrc<\/strong><\/em> in the same folder where the package.json is present and insert the following line:<\/p>\n\n\n\n
registry=https:\/\/npm.pkg.github.com\/OWNER<\/code><\/p>\n\n\n
\n{\u00a0\u00a0 \n\u00a0\u00a0\u00a0\u00a0\u00a0"name": "@accountgit\/packagename",\n\u00a0\u00a0\u00a0\u00a0\u00a0"version": "2.0.1",\n\u00a0\u00a0\u00a0\u00a0\u00a0"peerDependencies": {\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0"@angular\/common": "^8.2.14",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0"@angular\/core": "^8.2.14",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0"bootstrap": "^4.3.1",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0"ng2-dragula": "^2.1.1",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0...\n\u00a0\u00a0\u00a0\u00a0\u00a0},\n\u00a0\u00a0\u00a0\u00a0\u00a0"repository": {\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0"type": "git",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0"url": "git+https:\/\/github.com\/accountgit\/reponame.git"\n\u00a0\u00a0\u00a0\u00a0\u00a0}\n\u00a0\u00a0\u00a0\u00a0}\n<\/pre><\/div>\n\n\n
We can then publish it with the command:<\/p>\n\n\n\n
$ npm publish<\/code><\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
After the publication, we can find in our repository that the section package is populated, and it brings us a more detailed section on what has been published.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
How to modify the library<\/h2>\n\n\n\n
How can we manage the normal life cycle of our library, such as the correction of bugs, the addition of new features, a substantial modification that makes it incompatible with previous versions? All this, allowing anyone who has installed the library to update the package in their projects safely.<\/p>\n\n\n\n
It\u2019s time to manage the versioning of my library. In the package.json we find the field version<\/strong>, which defines the current version of the library. Using Semantic Version, we can clarify to those who use our library, which versions of our package can be installed safely, that is with no need to modify your code to integrate our library.
In this way, the version field contains a string formatted as \u201cmajor.minor.patch<\/strong>\u201d, where every block corresponds to a non-negative whole number. In the article by Antonio <\/a>, you can find more information.<\/p>\n\n\n\n
Let\u2019s come back to our modification: to solve our bugs, we must modify the patch<\/em> of our version number, increasing by one. After adding a new functionality compatible with the current code, we need likewise to update minor<\/em>, increasing it by one. Major<\/em> will be incremented when we make modifications that affect the API, as, in our case, the modification of the name of an INPUT property. As soon as we finish the modifications, we can publish the updated package, using the same command used before $ npm publish<\/code>.<\/p>\n\n\n\n
Regarding the clients using our library, following the command npm install<\/code>, its update (get with the command npm update<\/code>) depends on the configuration of the dependency in the package.json.<\/p>\n\n\n\n
We have two possible configurations:<\/p>\n\n\n\n