Angular Component Library mit ng-packagr erstellen

Update 11.05.2018

• Angular Directive nutzen: hier ngClass
• Assets für Component Library erstellen
• Kopieren der Assets integrieren

Angular Projekt mit Angular Cli erstellen

Mit der Angular Cli lässt sich mit folgendem Befehl sehr einfach ein neues Angular Projekt erstellen in dem die Component Library entwickelt wird:
ng new ng-my-lib

Test Library erstellen

Zu Testzwecken wird eine einfache Angular Component erstellt.
Hierfür wird der Ordner my-header im Rootverzeichnis erstellt (der Ordner kann aber auch nach belieben positioniert werden).
Nun wird die Datei my-header.component.ts mit folgendem Inhalt erstellt:

import { Component } from "@angular/core";

@Component({
    selector: 'my-header',
    template: `<h1 [ngClass]="{'custom-h1':true}"><ng-content></ng-content></h1>`
})
export class MyHeaderComponent { }

Diese wird anschließend im Module my-header.module.ts importiert und deklariert.

import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { MyHeaderComponent } from './my-header.component';

@NgModule({
    imports: [CommonModule],
    declarations: [MyHeaderComponent],
    exports: [MyHeaderComponent]
})
export class MyHeaderModule { }

Styling via SCSS hinzufügen

Dies dient nur zu Demonstationszwecken und als Nachschlag wie ich zurzeit „assets“ für Component Libraries behandele.
Dazu wird im Lib Order my-header der Ordner assets und die Datei styles.scss mit folgendem Inhalt erstellt:

.custom-h1 {
    color: red;
}

Dies soll als Indikator dienen, dass später der Import dieser Styles auch funktioniert.

Package ng-packagr installieren

Als nächstes wird das Package ng-packagr installiert, welches das Erstellen der Angular Component Library vereinfacht:
npm install ng-packagr --save-dev

Einstieg für ng-packagr konfigurieren

Das Package ng-packagr benötigt als Einstieg eine Datei, die das Module mit der Component exportiert.
Diese wird im Ordner der Library erstellt (hier in my-header).
Als Pattern setzt sich hierbei immer mehr die Benennung public_api.ts durch:

export * from './my-header.module'

ng-packagr konfigurieren

Zur Konfiguration von ng-packagr wird im Root-Verzeichnis der Angular Applikation die Datei ng-package.json mit folgendem Inhalt angelegt:

• lib: kennzeichnet hierbei die Einstiegs-Datei, die zuvor erstellt wurde – hier: public_api.ts
• dest: gibt das Ausgabeverzeichnis an
• whitelistedNonPeerDependencies: Wenn PeerDependencies als DevDependencies in der package.json definiert werden, kann man sie hier nachtragen, damit beim Builden keine Warnings oder Fehler angezeigt werden (je nach Version von ng-packagr).

{
    "$schema": "./node_modules/ng-packagr/ng-package.schema.json",
    "lib": {
        "entryFile": "my-header/public_api.ts"
    },
        "dest": "dist-ng-my-lib",
    "whitelistedNonPeerDependencies": [
        "angular",
        "core-js",
        "rxjs",
        "zone.js"
    ]
}

package.json ergänzen

Nun wird die scripts Section der package.json so ergänzt, dass sich mittels packagr Command das Builden der Angular Component Library starten lässt.

"scripts" : {
    ...
    "packagr": "ng-packagr -p ng-package.json"
    ...
}

Angular Component Library erstellen lassen

Nun kann die Angular Component Library über folgenden Befehl in einem Terminal (Rootverzeichnis) gestartet werden:
npm run packagr
Dies erstellt die Angular Component Library im Rootverzeichnis unter dist-ng-my-lib (siehe dest in ng-package.json).

Problem „assets“

Das automatische Integrieren von Styles und Assets war zur Zeit der Erfassung dieses Tutorials noch nicht integriert.
Abhilfe wird hier mittels copy, xcopy oder auch mit dem npm package copyfiles geschaffen.

copyfiles installieren

npm install copyfiles --save-dev

package.json erneut ergänzen

Mittels npx Befehl lassen sich lokal installierte Module ausführen.
Der folgende Befehl kopiert mittels copyfiles alle Inhalte aus assets und fügt sie in das dest-Verzeichnis der gebuildeten Component Library ein.

"scripts" : {
    ...
    "copy-files": "npx copyfiles -f './my-header/assets/*.*' './dist-ng-my-lib/assets'"
    ...
}

Assets kopieren

Hierfür wird das zuvor erstellte Script ausgeführt:

npm run copy-files

Angular Component Library lokal installieren

Die erstellte Angular Component Library lässt sich nun einfach lokal in andere Projekte installieren.
Hierfür wechselt man mittels Terminal unter das erstellte dest Verzeichnis und führt folgenden Befehl aus:
npm pack
Dies erstellt eine „ng-my-lib-0.0.0.tgz“ Datei.
Die erstellte .tgz sollte sich mittels 7.zip oder anderen Archiv-Manager öffnen lassen. In dieser sollte ebenfalls der Ordner assets enthalten sein.

Die .tgz lässt sich nun in einem anderem Projekt wie folgt installieren:

npm install ../PFAD-ZUR-LIB/dist-ng-my-lib/ng-my-lib-0.0.0.tgz

Modul importieren und Component integrieren

Nach der erfolgreichen Installation lässt sich das Modul MyHeaderModule in AppModule importieren.
Hierbei muss der Name aus der package.json der Component Library gewählt werden – hier „my-header“.

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

import { AppComponent } from './app.component';
import { MyHeaderModule } from 'my-header';

@NgModule({
    declarations: [AppComponent],
    imports: [BrowserModule, HeaderModule],
    providers: [],
    bootstrap: [AppComponent]
})
export class AppModule { }

Die Component lässt sich anschließend wie folgt benutzen:

<my-header>Some Header</my-header>

Styling integrieren

Abschließend lässt sich das Styling wie folgt in einer styles.scss Datei des neuen Projektes integrieren:

@import "~ng-my-lib/assets/styles";

Nach einem Reload sollte die Schrift nun in „rot“ eingefärbt werden.

Fazit

Mittels ng-packagr ist das Erstellen einer einfachen Angular Component Library viel einfacher.