{"id":27727,"date":"2020-01-08T00:00:00","date_gmt":"2020-01-07T23:00:00","guid":{"rendered":"https:\/\/blexin.com\/?p=27727"},"modified":"2021-01-13T09:40:17","modified_gmt":"2021-01-13T08:40:17","slug":"creare-librerie-di-componenti-angular","status":"publish","type":"post","link":"https:\/\/blexin.com\/it\/blog\/creare-librerie-di-componenti-angular\/","title":{"rendered":"Creare librerie di componenti Angular"},"content":{"rendered":"\n
\"\"<\/figure>\n\n\n\n

Capita spesso di dover risolvere un problema gi\u00e0 risolto in un progetto precedente con un classico copia e incolla del codice. Tale approccio, ovviamente, fornisce una soluzione rapida al problema, ma pu\u00f2 innescare una serie di effetti collaterali, tra cui il peggiore di tutti \u00e8 sicuramente scoprire la presenza di un bug e doverlo correggere in tutti i progetti in cui abbiamo copiato il codice. E se poi volessi aggiungere una nuova funzionalit\u00e0? Dovr\u00f2 propagarla ovunque?<\/p>\n\n\n\n

Nei progetti Angular su cui ho lavorato, \u00e8 sempre stato necessario creare un componente che fosse in grado di prendere dei dati e mostrarli in forma tabulare. Perch\u00e9 non rendere questo componente riutilizzabile in pi\u00f9 progetti? Angular offre questa possibilit\u00e0 con le Angular Library<\/strong>. Nell\u2019articolo precedente <\/a>, ho mostrato come creare un componente che visualizzi dei dati in forma tabellare, e permetta il drag and drop delle colonne: rendiamo questo componente riutilizzabile in tutti i nostri progetti creando una libreria!<\/p>\n\n\n\n

Dalla CLI<\/strong> di Angular lanciamo i seguenti comandi:<\/p>\n\n\n\n

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

In merito alla creazione di una libreria, la documentazione ufficiale di Angular ci dice di impostare il flag --create-application<\/code> a false per indicare alla CLI che non deve creare un\u2019applicazione iniziale ma semplicemente un workspace vuoto. Non \u00e8 per\u00f2 la soluzione che ho scelto e che preferisco, perch\u00e9 diventa poi difficile fare il debug della libreria.
Quello che invece vi consiglio, \u00e8 creare una classica applicazione Angular che vi faccia da host e al suo interno sviluppare la libreria: in questo modo potrete testarla prima di effettuarne il rilascio. Nella cartella radice del progetto, lanciamo il comando per creare la libreria:<\/p>\n\n\n\n

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

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

Notiamo che l\u2019Angular CLI ha creato una cartella projects con, al suo interno, una cartella col nome della libreria (DataTable). Nella sottocartella data-table\/src, troviamo una cartella\u00a0lib<\/em>\u00a0che conterr\u00e0 i file che compongono il progetto (componenti, servizi, moduli, etc), pi\u00f9 un file public-api.ts che dichiarer\u00e0 cosa vogliamo rendere disponibile agli utilizzatori della nostra libreria.<\/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
Scopriamo cos\u00ec che nella libreria \u00e8 gi\u00e0 stato creato un component, un service e un modulo. Il file di configurazione dell\u2019intero workspace,\u00a0angular.json<\/strong>, viene aggiornato con un nuovo progetto di tipo\u00a0library<\/strong>\u00a0che ha il nome scelto durante la creazione della libreria.<\/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
A questo punto, procediamo scrivendo codice come in un progetto Angular standard. Prendendo spunto dal mio articolo precedente <\/a>, eliminiamo i file che ci ha creato la CLI lasciando data-table.component.ts<\/strong><\/em> e data-table.module.ts<\/strong><\/em>, e passiamo alla costruzione del component.<\/p>\n\n\n\n
Nell\u2019articolo precedente, la tabella non era un componente a s\u00e9 ma faceva parte dell\u2019app.component: quindi, un passaggio obbligatorio \u00e8 quello di estrarre il component data-table dall\u2019app.component.
Osservando il template, ci accorgiamo che data-table opera fondamentalmente su due strutture dati:\u00a0columns<\/strong>\u00a0e\u00a0rows<\/strong>. Queste due strutture dati devono esserci fornite da chi utilizza la libreria, diventando quindi i nostri\u00a0Input<\/strong>. Il file .ts del nostro component sar\u00e0 il seguente:<\/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
Modifichiamo il selettore da\u00a0lib-DataTable<\/strong>\u00a0a\u00a0blx-data-table<\/strong>, andando anche a modificare il prefix nel 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
Di seguito potete vedere anche il template del nostro componente:<\/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
La libreria esterna che stiamo utilizzando per il drag&drop necessita di alcune classi CSS, per poter mostrare l\u2019effetto desiderato. Nel progetto precedente, avevo messe queste classi nello style.css<\/strong>. Ora, per\u00f2, non voglio che chi importa la libreria debba preoccuparsi di aggiungere tali classi al suo progetto: devono gi\u00e0 essere presenti nella libreria stessa.
Le includiamo quindi nel file data-table.component.css<\/strong>.<\/p>\n\n\n\n
Come gi\u00e0 detto, il file\u00a0public_api.ts<\/strong>\u00a0permette di definire ci\u00f2 che i nostri utilizzatori vedranno della libreria. Andiamo quindi a modificarlo, per tener conto della cancellazione del service:<\/p>\n\n\n
\nexport * from '.\/lib\/data-table.component';\nexport * from '.\/lib\/data-table.module';\n<\/pre><\/div>\n\n\n
Il componente\u00a0data-table<\/strong>\u00a0necessita di alcune dipendenze esterne:\u00a0ng2-dragula<\/code>\u00a0(gestione drag&drop) e\u00a0bootstrap<\/code>\u00a0(classi CSS). \u00c8 necessario, quindi, comunicare a chi installa la libreria che, per il corretto funzionamento, ha bisogno di aggiungere al proprio progetto tali dipendenze. Modifichiamo quindi il file\u00a0package.json<\/strong>\u00a0della cartella data-table, aggiungendole alla sezione\u00a0peerDependencies<\/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
Prima della pubblicazione, dobbiamo assicurarci che il tutto funzioni correttamente. La scelta iniziale di creare un progetto Angular, e non un workspace vuoto, ora ci d\u00e0 un enorme vantaggio: per poter testare la libreria \u00e8 sufficiente importarne il modulo nel nostro app.module e utilizzare il component mediante il selettore. Ecco come diventa il nostro\u00a0app.component.html<\/strong>:<\/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
dove column e row vengono definite in\u00a0app.component.ts<\/strong><\/em>\u00a0e poi passate in input al\u00a0data-table<\/strong>. Prima di poter lanciare la nostra applicazione, occorre installare le due dipendenze della nostra libreria (con le istruzioni\u00a0npm install ng2-dragula<\/code>\u00a0e\u00a0npm install bootstrap<\/code>), aggiungere\u00a0\"node_modules\/bootstrap\/dist\/css\/bootstrap.css\"<\/code>\u00a0tra gli style del nostro\u00a0angular.json<\/strong>\u00a0ed infine aggiungere\u00a0(window as any).global = window;<\/code>\u00a0nel file\u00a0polyfills.ts<\/strong>\u00a0come suggerito nella documentazione di Dragula.<\/p>\n\n\n\n
Lanciamo quindi l\u2019applicazione con il classico\u00a0ng serve<\/code><\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Verificato che tutto funziona, possiamo distribuirla. Compiliamo la libreria, aggiungendo al solito comando di build il nome della libreria:<\/p>\n\n\n\n
ng build DataTable<\/code><\/p>\n\n\n\n
A fine compilazione, la libreria sar\u00e0 disponibile nella cartella dist.<\/p>\n\n\n\n
Come utilizzare la libreria appena creata<\/h2>\n\n\n\n
Abbiamo due possibilit\u00e0: importarla in un nuovo progetto prelevandola dal suo folder dist oppure renderla disponibile assieme ai suoi aggiornamenti utilizzando lo stesso ecosistema scelto da Angular: npm.
Creiamo un nuovo progetto Angular:<\/p>\n\n\n\n
ng new demo-with-lib<\/code><\/p>\n\n\n\n
All\u2019interno della struttura del progetto appena creato, andiamo a creare una nuova cartella lib<\/em> dove copiamo la cartella contenente il risultato della build della libreria. Posso quindi installarla con il comando:<\/p>\n\n\n\n
npm i .\/libs\/data-table<\/code><\/p>\n\n\n\n
Aggiungiamo anche le dipendenze necessarie al suo corretto funzionamento ed importiamo il modulo\u00a0DataTableModule<\/code>\u00a0nel\u00a0app.module.ts<\/em>\u00a0per poter utilizzare il component esposto.<\/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
Posizioniamo il componente con l\u2019opportuno tag\u00a0blx-data-table<\/code>\u00a0nel\u00a0app.component.ts<\/em>, fornendo gli Input attesi:<\/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
Lanciamo l\u2019applicazione e verifichiamo il corretto funzionamento.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Abbiamo fatto dei progressi, nel senso che possiamo riutilizzare il componente ovunque vogliamo. In realt\u00e0, abbiamo di nuovo fatto ricorso a un copia e incolla: non pi\u00f9 del codice sorgente ma del folder di distribuzione della libreria. E se volessimo permettere ad altri elementi del team di utilizzare la libreria, fornendo uno strumento semplice per seguire i suoi aggiornamenti? E se volessi renderla pubblica, ossia permettere a chiunque nel mondo di installarla tramite npm?<\/p>\n\n\n\n
All\u2019indirizzo https:\/\/docs.npmjs.com\/creating-and-publishing-private-packages <\/a>, \u00e8 disponibile il tutorial ufficiale per pubblicare un package sul registy pubblico npm. Seguiamo invece una strada diversa, offerta da qualche mese a questa parte da Github.<\/p>\n\n\n\n
GitHub offre la possibilit\u00e0, mediante GitHub Packages<\/strong>, di creare un proprio repository, dove pubblicare e distribuire la propria libreria in maniera privata con il proprio team oppure pubblica.<\/p>\n\n\n\n
Pubblicare su GitHub Packages<\/h2>\n\n\n\n
Per poter pubblicare, installare ed eventualmente eliminare un package da GitHub Packages \u00e8 necessario disporre di un access token. Ci sono due strade per ottenerne uno: utilizzando l\u2019Access Token personale con la propria username per autenticarsi su GitHub, oppure utilizzando un GITHUB_TOKEN per autenticarsi su GitHub Actions.<\/p>\n\n\n\n
Ho scelto la strada dell\u2019access token personale. Occorre quindi modificare il file ~\/.npmrc<\/strong><\/em> ed includere la seguente riga:<\/p>\n\n\n\n
\/\/npm.pkg.github.com\/:_authToken=TOKEN<\/code><\/p>\n\n\n\n
sostituendo \u201cTOKEN\u201d con il proprio token.<\/p>\n\n\n\n
A questo punto, occorre creare il file .npmrc<\/strong><\/em> nella stessa cartella dove \u00e8 presente il package.json, nella quale inserire la seguente riga:<\/p>\n\n\n\n
registry=https:\/\/npm.pkg.github.com\/OWNER<\/code><\/p>\n\n\n\n
dove OWNER \u00e8 il nome dell\u2019account Git del repo. Aggiungiamo lo stesso file anche sul repo e controlliamo che nel package.json sia specificato il nome del pacchetto, la versione e il repo dove risiede il codice sorgente.<\/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
Possiamo pubblicarlo con il comando:<\/p>\n\n\n\n
$ npm publish<\/code><\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
A seguito della pubblicazione, nel nostro repository troviamo popolata la sezione package che ci porta a una sezione pi\u00f9 dettagliata su quanto \u00e8 stato pubblicato.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Come modificare la libreria<\/h2>\n\n\n\n
Come possiamo gestire il normale ciclo di vita della nostra libreria? La correzione dei bug, l\u2019aggiunta di una nuova feature, una modifica sostanziale che la renda incompatibile con le versioni precedenti? Tutto ci\u00f2, consentendo a tutti quelli che hanno installato la libreria di aggiornare il pacchetto nei propri progetti in maniera sicura.<\/p>\n\n\n\n
\u00c8 il momento di gestire il versionamento della mia libreria. Nel package.json troviamo il campo version<\/strong>, che definisce la versione attuale della libreria. Utilizzando Semantic Version, possiamo rendere chiaro a chi utilizza la nostra libreria quali versioni del nostro pacchetto pu\u00f2 installare in maniera sicura, ovvero senza la necessit\u00e0 di dover apportare modifiche al proprio codice per integrare la nostra libreria.
In questo modo, il campo version conterr\u00e0 una stringa formattata nel modo seguente: \u201cmajor.minor.patch<\/strong>\u201d, in cui ogni blocco corrisponde ad un numero intero non negativo. Vi rimando all\u2019 articolo di Antonio<\/a> per una spiegazione dettagliata<\/p>\n\n\n\n
Tornando alla nostra modifica: per la risoluzione dei bug occorrer\u00e0 quindi modificare la patch<\/em> del nostro numero di versione, incrementando di uno. Allo stesso modo, dopo aver aggiunto una nuova funzionalit\u00e0 che sia compatibile con il codice attuale, occorrer\u00e0 aggiornare minor<\/em> incrementando di uno. Major<\/em> sar\u00e0 incrementato quando verranno apportate delle modifiche che impattano sull\u2019API, come ad esempio, nel nostro caso, la modifica di un nome di una propriet\u00e0 di INPUT. Terminate le modifiche, possiamo pubblicare il pacchetto aggiornato con lo stesso comando utilizzato in precedenza $ npm publish<\/code><\/p>\n\n\n\n
Per i client che utilizzano la nostra libreria, a seguito del comando npm install<\/code>, l\u2019aggiornamento della stessa (ottenuto lanciando il comando npm update<\/code>)dipende dalla configurazione della dipendenza nel package.json.<\/p>\n\n\n\n
Ci sono due possibili configurazioni<\/p>\n\n\n\n