Ivanbtrujillo-angular2-library-example NPM

Como crear un modulo para Angular 2 y publicarlo en NPM

Estructura de archivos sin compilar:

index.ts

Estos archivos definen la API publica de modulo, es decir, los archivos que queremos que sean accesibles por nuestros usuarios.

carpeta src

Esta carpeta contiene nuestro componente en typescript y el tsconfig.json necesario para compilar el componente.

package.json

Define los scripts para compilar el módulo y sus dependencias

Estructura de archivos tras compilar

carpeta dist

Esta carpeta contiene el resultado del módulo listo para producción tras ser compilado a través del compilador de typescript

Formato CommonJS

Cada archivo Javascript sigue el formato de modulos ES2015, exportando sus dependencias via export y permitiendo que posteriormente podamos importar nuestro module con la sentencia import (al igual que hacemos en Angular 2).

Minificacion de archivos

A la hora de publicar nuestro módulo, podemos publicarlo sin minificar y minificada. Al publicarlo sin minificar, es decir, el codigo fuente, permitimos a los consumidores de nuestro módulo que puedan hacer sus propias modificaciones y añadirlas a los task runner que usen. Al publicarlo minificada restringimos y ofuscamos nuestro codigo y solo damos acceso a la API de nuestro módulo, de esta forma aseguramos que solo usarán las utilidades que nosotros queramos.

Creando nuestro módulo

Lo primero es crear la carpeta src donde almacenaremos el core de nuestro módulo. Primero creamos el componente que vamos a exportar en el archivo HelloWorld.ts:

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

@Component({
    selector: 'hello-world',
    styles: [`
       h1 {
          color: blue;
       }
    `],
    template: `
    <div>
        <h1 (click)="onClick()">{{message}}</h1>
    </div>`
})
export class HelloWorld {
  message = "Click Me ...";

  onClick() {
      this.message = "Hello World!";
      console.log(this.message);

  }

}

Lo siguiente es crear el archivo module.ts en el cual declaramos el módulo general, las declaraciones (lo que usa nuestro modulo) y lo que vamos a exportar:

import {NgModule} from '@angular/core';
import { HelloWorld } from './HelloWorld';

@NgModule({
  declarations: [
    HelloWorld,
  ],
  exports: [
    HelloWorld,
  ],
})
export class HelloWorldModule {}

Por último, fuera de la carpeta src creamos un index.ts el cual será el punto de entrada a nuestro módulo / librería. Aqui definimos la API publica de nuestra librería, en este caso damos acceso al Modulo que a su vez contiene el componente haciendo un export/import:

export * from './src/module';

Con esto ya tenemos creado nuestro componente, el módulo que lo envuelve y el punto de entrada a nuestra libreria. Lo siguiente que debemos de hacer es configurar el compilador de Typescript para compilar nuestro módulo a ES6.

Configurando el compilador de Typescript

Lo primero que debemos hacer es crear un fichero tsconfig.json en la raiz de nuestro módulo con el siguiente contenido:

{
  "compilerOptions": {
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "lib":[
      "dom",
      "es2015"
    ],

    "module": "es2015",
    "moduleResolution": "node",
    "outDir": "dist",
    "target": "es5",
    "declaration": true,
    "removeComments": true,
    "sourceMap": true
  },
  "angularCompilerOptions": {
    "skipTemplateCodegen": true,
    "skipMetadataEmit": false
  },
  "files": [
    "index.ts"
  ]
}

A continuacion, instala typescript de forma global ( npm i -g typescript) si no lo tienes instalado, ya que es necesario para poder compilar nuestro modulo.

Definiendo el package.json de nuestra librería

Cremos nuestro fichero package.json en la raiz de la librería y definimos un script para compilar la librería ejecutando npm init en la raiz. Tras contestar las preguntas tendremos lo siguiente:

{
  "name": "ivanbtrujillo-angular2-library-example",
  "version": "1.0.0",
  "description": "An example library",
  "main": "dist/index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "angular2",
    "library",
    "example"
  ],
  "author": "Iván Bacallado Trujillo",
  "license": "MIT"
}

A continuación definiremos un nuevo script para compilar el archivo usando el compilador de Typescript.

"scripts": {
  "build": "rm -rf dist && tsc"
}

Este script puede ser ejecutado de la siguiente forma:
```npm run build ````

El script lo que hace es borrar la carpeta dist (si la hubiera) y generar una nueva carpeta dist con el contenido compilado listo para publicar.

## Dependencias

En el package.json debemos definir las dependencias de nuestra librería. En devDependencies añadiremos typescript ya que es la librería que necesitamos para compilar el modulo:

"devDependencies": { "typescript": "^2.3.3" },

En dependencies añadiremos el core de angular:
```
  "dependencies": {
    "@angular/core": "4.1.2",
  },
```

## Ignorando ficheros

Nuestra idea es subir a Github el codigo completo de nuestro componente y a NPM solo la version para producción. Para ignorar ciertos archivos para Github, debemos 
definir lo que vamos a ignorar en un .gitignore en la raiz de nuestro modulo:

```
node_modules
```

Y para hacer lo mismo pero para npm, lo haremos en un .npmignore. Para ello ignoramos node_modules y en este caso, tambien el src y el index.ts ya que no queremos publicar el codigo fuente. 
También ignoraremos el gitignore y el tsconfig.json ya que no son necesarios para la version distribuida:
```
node_modules
/src
index.ts
tsconfig.json
.gitignore
```

Hay que prestar especial importancia al /src. Si no añadimos la / delante, ignorará todas las carpetas src (la que se genera dentro de /dist también) por lo que nuestra librería fallará al instalarla desde npm.

## Compilando y utilizando el módulo de forma Local

Ejecutamos npm run build y compilamos el módulo. Ahora para utilizarlo, en el app.module.ts de nuestro proyecto angular lo importamos:

```
import { HelloWorldModule } from './../components/angular2-library-example/dist';

Y lo añadimos al array de imports:

imports: [
    HelloWorldModule,
  ],

Con esto ya podemos llamar a en cualquier parte de nuestra app y utilizarlo.

Publicando a npm, instalando y usando el módulo

Lo primero que debemos hacer es crear una cuenta en npmjs.com y una vez lo hayamos hecho, seteamos nuestro usuaro en nuestro npm local mediante el comando:

npm adduser

Aqui pondremos nuestro usuario, contraseña y email de npm.

Antes de publicar debemos de tener en cuenta dos cosas:

El name de tu package.json hara referencia al nombre de la librería en npm. No puedes usar la nomenclatura con @ (por ejemplo @ivanbtrujillo/example) si no tienes una cuenta de pago de npm. Es el motivo por el cual angular cli se denomina @angular/cli.
El main de tu package.json hara referencia al archivo de entrada de nuestra aplicación. Deberá de ser /dist/index.js ya que es el fichero que nosotros vamos a publicar en npm (recuerda que no publicamos )

Ahora para publicarlo ejecutamos:

npm publish

Si todo va bien, nuestro modulo se debe haber publicado en npm. Ahora para instalarlo lo haremos desde la carpeta de nuestro proyecto mediante el comando:

npm install --save nombre-de-tu-paquete

En mi caso:
npm install --save ivanbtrujillo-angular2-library-example

Ahora podremos importarlo como un módulo mas:

import { HelloWorldModule } from 'ivanbtrujillo-angular2-library-example/dist';

Recuerda que cada vez que hagas cambios en la librería, deberás incrementar la version en el package.json para poder publicarlo en npm.

Empaquetando todo en dist

Nuestro modulo funciona pero tenemos que hacer el import desde dist. Vamos a crear un script en npm que simplemente copie package.json y el readme.md a la carpeta dist. De esta forma, ahora publicaremos desde dentro de la carpeta dist y así nuestros usuarios podrán importar la librería de la siguiente forma:

import { HelloWorldModule } from 'ivanbtrujillo-angular2-library-example'

El script lo llamaremos "copy-files" y será de la siguiente forma:

"copy-files": "cp package.json dist && cp readme.md dist"

Ahora nuestro .npmignore ya no es necesario y podemos borarlo.

También debemos de cambiar el "main" de nuestro package.json de /dist/index.js a simplemente index.js

A continuación, ejecutamos de nuevo la secuencia:

Cambiamos la version en el package.json
Generamos la version para npm: npm run build
Copiamos los archivos package.json y readme.md en /dist: npm run publish (es posible que pida sudo)
Publicamos la librería en npm: cd /dist + npm publish

Recuerda que para instalar de nuevo la librería, debes moverte al la raiz de tu proyecto.

angular2 library example

@angular/core

@everything-registry/sub-chunk-1943 @zalastax/nolb-iv

7 years ago

7 years ago

7 years ago

7 years ago