¿Cómo crear bibliotecas Angular y publicarlas? (con un ejemplo)

Devolver algo a la comunidad es una idea que me gusta mucho. Me parece muy importante compartir los conocimientos y resultados, ya que te permite aprender mucho de otros desarrolladores.

Te recomiendo encarecidamente que establezcas una práctica para compartir tu trabajo (por ejemplo, código, resultados e ideas). Puede ser un componente reutilizable como un componente de interfaz de usuario o una herramienta como la que estoy usando como ejemplo para este artículo, o simplemente algún truquito ingenioso.

Aquí hay un artículo que habla de las ventajas de publicar tus paquetes npm con más detalle:

El articulo está basado en la creación de algunos decoradores para depurar @ngrx/component-stores, y su publicación como una librería Angular en npmjs.org para facilitar su uso a otros desarrolladores.

En esta guía paso a paso, explicaré cómo se creo la librería y también una aplicación demo para ella, y cómo se publico la librería en npmjs.org y la aplicación demo en StackBlitz.

Puedes encontrar el código fuente completo de la librería y la aplicación demo en mi Github. También puedes probar la aplicación demo en StackBlitz.

Puedes encontrar el código fuente completo de la biblioteca y la aplicación de demostración en Github. También puedes probar la aplicación de demostración en StackBlitz.

Creación de un espacio de trabajo multiproyecto

Como primer paso, creamos un espacio de trabajo multiproyecto para nuestra biblioteca y aplicación de demostración. Cree el espacio de trabajo:

ng new ngx-ngrx-component-store-debug-tools --no-create-application

Generar el ngx-ngrx-component-store-debug-tools en el espacio de trabajo:

cd ngx-ngrx-component-store-debug-tools
ng generate library ngx-ngrx-component-store-debug-tools

A continuación, genera una demo aplicación en el espacio de trabajo:

ng generate application demo

El generador hace las siguientes preguntas:

¿Desea añadir enrutamiento Angular? N
¿Qué formato de hoja de estilo desea utilizar? SCSS

Una vez completado el comando ng generate, encontramos dos nuevos directorios de proyecto en nuestro espacio de trabajo: el directorio projects/demo para la aplicación y el directorio projects/ngx-ngrx-component-store-debug-tools para la librería. El generador también instala algunos paquetes adicionales.

Si tu quieres saber más acerca de crear una libreria en angular, te dejo el siguiente video.

Implementación de nuestra biblioteca

Tenemos un module, un component y unsrc/lib en el directorio src/lib de la biblioteca. Estos archivos son útiles para crear un componente o servicio reutilizable. Dado que nuestro objetivo es sólo compartir unos pocos decoradores y funciones de utilidad, eliminar estos archivos, y crear un archivo

src/lib/ngx-ngrx-component-store-debug-tools.ts:

// import ...

export function LogUpdater(params: LoggerParams) {
  // ...
}

export function LogEffect(params: LoggerParams) {
  // ...
}

export function LogObservable(groupMessage: string, observable: Observable<any>, initialState: any, logLevel: LogLevel = 'log'): Subscription | undefined {
  // ...
}

export function LogState(params: LoggerParams) {
  // ...
}

La API pública de la librería se exporta a través del archivo src/public-api.ts, así que vamos a actualizarlo. Eliminamos las exportaciones existentes y solo exportamos el archivo que creamos en el paso anterior:

/*
* Public API Surface of ngx-ngrx-component-store-debug-tools
*/
export * from './lib/ngx-ngrx-component-store-debug-tools';

También ampliamos el archivo projects/ngx-ngrx-component-store-debug-tools/package.json añadiendo los atributos description, repository, keywords, author, license y bugs:

{
  "name": "ngx-ngrx-component-store-debug-tools",
  "version": "0.0.6",
  "description": "Debug decorators and utilities for @ngrx/component-store",
  "repository": {
    "type": "git",
    "url": "https://github.com/gergelyszerovay/ngx-ngrx-component-store-debug-tools.git"
  },  
  "keywords": [
    "Angular",
    "Redux",
    "NgRx",
    "Schematics",
    "Local State",
    "Component State",
    "State management"
  ],
  "author": "Gergely Szerovay",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/gergelyszerovay/ngx-ngrx-component-store-debug-tools/issues"
  },  
  "peerDependencies": {
    "rxjs": "~7.5.0"
  },
  "dependencies": {
    "tslib": "^2.3.0",
    "recursive-diff": "^1.0.8"
  }
}

Dependencias

Nuestra librería tiene las siguientes dependencias:

tslib: Es añadida por el generador, ya que es necesaria para que una librería Angular funcione
recursive-diff y rxjs

Como regla general, debemos añadir nuestras dependencias como una dependencia de pares. Sin embargo, los dos gestores de paquetes, npm y yarn manejan las dependencias pares de forma diferente: npm las instala por defecto, mientras que yarn no.

Dado que es muy poco probable que alguien utilice recursive-diff en una aplicación Angular, lo he añadido como dependencia al package.json, por lo que tanto npm como yarn instalarán este paquete automáticamente.

En caso de que queramos añadir el paquete recursive-diff como dependencia de pares, las aplicaciones que utilicen nuestra librería tendrán que incluir el paquete recursive-diff en su fichero packages.json para que nuestra librería funcione.

Añadimos el paquete rxjs como una dependencia de pares, ya que cada aplicación Angular utiliza rxjs, por lo que nuestra biblioteca puede utilizar el paquete rxjs instalado por la aplicación.

Implementación de la aplicación de demostración

En el directorio /projects/demo/src/app/card, creamos un componente de tarjeta simple con un almacén de componentes, y usamos los decoradores de la librería. Podemos simplemente importar nuestra librería, y luego usar sus decoradores:

import { LogUpdater, LogEffect } from "ngx-ngrx-component-store-debug-tools"

const logLevel = 'debug';

@Injectable()
@LogState({ logLevel })
export class CardStore extends ComponentStore<CardState> {
  // ...
}

El archivo /tsconfig.json contiene la siguiente ruta:

"paths": {      
  "ngx-ngrx-component-store-debug-tools": [        
    "dist/ngx-ngrx-component-store-debug-tools"      
  ]    
},

Así que por defecto, el import { LogUpdater, LogEffect } de "ngx-ngrx-component-store-debug-tools" importa la versión construida de la librería del directorio dist/ngx-ngrx-component-store-debug-tools.

Sugiero cambiar la ruta al archivo projects/ngx-ngrx-component-store-debug-tools/src/public-api.ts, de esta forma no tendremos que construir la librería antes de ejecutar la aplicación demo:

"paths": {      
  "ngx-ngrx-component-store-debug-tools": [        
    "projects/ngx-ngrx-component-store-debug-tools/src/public-api.ts"      
  ]    
},

Aplicando esta configuración, si cambiamos el código fuente de la librería, la demo app recompilará automáticamente.

Construyendo la librería e iniciando la aplicación demo

Construimos nuestra librería usando el comando ng build ngx-ngrx-component-store-debug-tools, que construye la librería en el directorio dist/ngx-ngrx-component-store-debug-tools.

Si la ruta ngx-ngrx-component-store-debug-tools en el archivo tsconfig.json apunta a la librería construida, tenemos que reconstruir la librería después de cada cambio en el código fuente. Sin embargo, podemos automatizar este proceso aplicando el comando ng build ngx-ngrx-component-store-debug-tools --watch, que reconstruye nuestra librería con los cambios en el código fuente automáticamente.

Utilice el comando ng serve demo para ejecutar la aplicación de demostración.

Publicando la librería

Antes de publicar la biblioteca, se había creado una cuenta npmjs.org aquí. Se había configurado la autenticación de dos factores y había iniciado sesión en la línea de comandos utilizando el comando npm login.

Luego de navegar al directorio dist/ngx-ngrx-component-store-debug-tools y publicar la librería usando el comando npm publish.

En caso de que quieras actualizar la librería ya publicada, actualiza el número de versión del paquete en el archivo projects/ngx-ngrx-component-store-debug-tools/package.json, luego construye y publica el paquete.

Ejecutar la aplicación de demostración en StackBlitz

Cuando se intento ejecutar el espacio de trabajo multi-proyecto, se presentaron los siguientes problemas:

StackBlitz no maneja bien los espacios de trabajo multi-proyecto de Angular
la demo contiene TailwindCSS, pero los componentes dentro de la app se mostraban sin ningún estilo en StackBlitz.

Para solucionar el primer problema (espacios de trabajo multi-proyecto), se creo un espacio de trabajo de un solo proyecto aplicando el comando ng new ngx-ngrx-component-store-debug-tools-demo, y se copio la aplicación de demostración del directorio project/demo/src en él. Puedes encontrar el código fuente completo aquí.

El archivo package.json del proyecto hace referencia a la biblioteca como una dependencia simple:

{  
  "name": "ngx-ngrx-component-store-debug-tools-demo",
...
  "dependencies": {
...
    "ngx-ngrx-component-store-debug-tools": "^0.0.6",
...
  },
...
}

En cuanto al segundo problema, para que TailwindCSS funcionara en StackBlitz, se añadió la siguiente etiqueta

<!doctype html>
<html lang="en">
  <head>
...
    <!-- We need this on StackBlitz -->
    <script src="https://cdn.tailwindcss.com"></script>
...
  </head>
  <body>
...
  </body>
</html>

🎉¡Sí!
Así que ya tenemos una librería Angular publicada y funcionando completamente, bastante bien, ¿no? ¡Te animo a replicar este proceso mostrado arriba! Hazme saber si te has encontrado con algún problema o si conoces algún truco.

Fuente