Angular2-Component-library

Un exemple de librairie Angular2 packagée avec webpack, réutilisable (sous conditions) dans nos applications.

Objectif

Trouver et montrer comment on peut s'y prendre pour écrire une bibliothèque de composants en Angular2.

• Expliquer les règles à suivre, les limites.
• Expliquer comment packager.
• Expliquer comment interagir avec NPM (version, publish.
• Expliquer comment l'application cliente doit être conçue pour pouvoir utiliser ces composants.
• Expliquer comment installer ce composant dans l'application.

Ecriture des composants

• Les composants sont écrits en Typescript avec les restrictions suivantes:
  • Le style est écrit en CSS, SASS n'est pas supporté (pour le moment).
  • le HTML et le CSS peut être inliné ou externalisé dans un fichier séparé. Cela se fait de la façon suivante: Exemple:

@Component({
    selector: 'zas-footer',
    pipes: [TranslatePipe],
    styleUrls: [require('./footer.component.css'],
    templateUrl: require('./footer.component.html')
})

• les traductions sont de la responsabilité exclusive de l'application appelante, pour le moment. A voir si à terme chaque composant devrait être responsable de ses propres traductions (ce n'est pas forcément une bonne option).

• Les images sont toutes dans un seul répertoire "img".

• Elles partagent un préfixe spécifique à la librairie. Ex. la librairie "ma-librairie" a pour préfixe "lib" (image "lib-closemenu.png" etc.). Cela permet d'éviter l'écrasement entreimages provenants de différentes librairies ou avec celles de l'application cliente.

• un fichier typescript portant le nom de la librairie exporte tous les composants de la librairie. Ex. "ma-librairie.ts" exporte les interfaces publiques de la librairie "ma-librairie". Cela simplifie l'utilisatin de la librairie par les applications.

• un fichier CSS portant le nomde la librairie exporte toutes les images de la librairie. Ex. "ma-librairie.css" exporte autant de classes que la librairie a d'images, chaque classe portant le nom d'une image et pointant sur l'image. Cela permetà l'application, packagée avec Webpack, d'inclure ces images dans ses bundles.

.openmenu {
    background-image: url('img/lib-openmenu.png');
}

• Important: aucune URL absolue n'est utilisée pour désigner un fichier, que ce soit une image, un fichier HTML ou un css.

publication de la librairie

pour publier la librairie il faut disposer d'une registry NPM. Soit on utilise la registry registry.npmjs.org, soit on utilse un outil interne. J'utilise par exemple l'outil "Sinopia", installable via npm https://www.npmjs.com/package/sinopia-altldap . la registry est alors accessible sur localhost:4873 .

La gestion des versions doit être conforme aux principes de semver (semantic versioning). Pour simplifier, x.y.z avec x=version majeure, y=version mineure et z=patch. Toute rupture de compatibilité dans une nouvelle version implique la création d'une version majeure. Une version mineure apporte des nouveautés compatibles, et des corrections. Un patch n'est que correctif.

Utilisation de NPM. Une fois le commit de la librairie effectué, utiliser la commande

• npm version major|minor|patch selon le niveau de compatibilité (note: il y a d'autres poptions, se reporter à l'aide NPM)

• Compiler la librairie par "typings install" puis "tsc". Cela génère une partie du répertoire "dist" de distribution

• puis utiliser "npm publish". Le script "prepublish" sera exécuté au préalable. Je l'utilise pour copier des fichiers annexes dans le répertoire de distribution.

Utilisation de la librairie dans une application tierce

• utiliser la commande "npm i --save ma-librairie[@x.y.z si la version doit être précisée]"

• dans le vendor.ts importer le fichier "ma-librairie.css" pour déclencher la copie par webpack des images nécessaires au composant dans l'application.

• dans le fichier typescript décrivant la page, importer le composant FooterComponent

import {FooterComponent} from 'ma-librairie/dist/ma-librairie';

@Component({ selector: 'app', encapsulation: ViewEncapsulation.None, directives: [HeaderComponent, FooterComponent, SideMenu], styleUrls: [ './app.component.scss' ], template: '<div class="application application-scrolling"> <zas-header (langChanged)="translate.setLang($event)" [currentLang]="translate.getLang()"></zas-header> <main> <div class="router-outlet"> <router-outlet></router-outlet> </div> </main> <zas-footer></zas-footer> </div> })