Esquemas Angular para bibliotecas: cómo mantener actualizados sus proyectos

Angular esquemas existen desde hace algún tiempo, y creo que la mayoría de nosotros nos hemos acostumbrado a trabajar con ellos y a disfrutar de sus muchas ventajas. Desde la ejecución de un simple ng new hasta la creación de esquemas complejos que automatizan el flujo de trabajo y la configuración del proyecto, el motor de esquemas es una parte importante del ciclo de vida de cualquier aplicación Angular.

Pero, ¿qué pasa con una biblioteca Angular?

En Infragistics, nos enorgullecemos de desarrollar y mantener nuestra biblioteca de componentes Angular de código abierto. Pero con la biblioteca ganando cada vez más usuarios, y la naturaleza en constante evolución de Angular, necesitábamos proporcionar una manera fácil de mantener los proyectos actualizados. Aquí es donde, como ocurre con la mayoría de las cosas Angular, entran en juego los esquemas.

ng add, ng update and more

En este blog, le mostraremos cómo configurar su biblioteca para que aproveche al máximo los comandos ng add y ng update de Angular CLI. Lo haremos definiendo colecciones esquemáticas de una manera específica.

Disclaimer: 

Para aprovechar al máximo este post, lo ideal es que ya estés familiarizado con los conceptos básicos de Angular esquemas, y puede que te interesen algunos de los Otro Bien Mensajes en Medio.

Tomando prestado un artículo reciente de angular.io:

 Un esquema es un generador de código basado en plantillas que admite lógica compleja. Es un conjunto de instrucciones para transformar un proyecto de software mediante la generación o modificación de código. Los esquemas se empaquetan encoleccionesy se instalan con npm.

Try Ignite UI for Angular

¿Qué son Angular esquemas?

Los esquemassonel componente básico delaAngular CLI. Son conjuntos de instrucciones ejecutables que realizan manipulaciones en archivos existentes o generan archivos/contenido.Si eres un desarrollador Angular, lo más probable es que hayas utilizado la creación de un componente ejecutando: 

ng g c [component name] 

Los esquemas son una gran parte del ecosistema de Angular y comprenderlos mejor puede mejorar en gran medida su vida y la de sus usuarios.

Repasaremos un rápido tutorial de esquema angular para que pueda familiarizarse con los conceptos básicos antes de profundizar más.

Creación de esquemas Angular

Puede comenzar rápidamente a crear sus propios esquemas aprovechando la propia cli de esquemas de Angular.

Simplemente ejecute lo siguiente para instalarlo globalmente:

npm install -g @angular-devkit/schematics-cli

Y, a continuación, cree un esquema de ejemplo en blanco listo para usar llamando: 

schematics blank --name=intro-schematic

Si revisa los archivos generados, puede revisarlos para averiguar cómo se exponen exactamente los esquemas utilizados.

1. En el archivo package.json, puede ver que hay una propiedad "schematics", que apunta a un "collection.json"
2. Siguiendo esa ruta, puede inspeccionar ese archivo: es un archivo de .json bastante estándar, con una cosa clave: una propiedad "esquemas", que es una lista de todos los esquemas que se exponen a los usuarios.
   Justo después de ejecutar el comando de ejemplo desde arriba, la lista solo debe tener una entrada: "Esquemas de introducción". La entrada contiene una breve descripción y una referencia a una "fábrica": aquí es donde se define el cuerpo del esquema.
3. En el archivo 'index.ts' referido, se define el "cuerpo" de los esquemas, una 'Regla' que se ejecutará en el contexto del proyecto de consumo y donde residirá toda su lógica personalizada

Ahora puede llamar a su ejemplo desde fuera del proyecto llamando:

ng g [path-to-collection.json]:intro-schematics

Pero esa no es la única forma de llamar a los esquemas. Angular han expuesto"ganchos" convenientes para los desarrolladores que pueden automatizar aún más la experiencia de sus usuarios.

Angular Puntos de entrada esquemáticos

Aparte de llamar a un esquema Angular con el esquema habitual

ng g my-custom-library:schematics [args]

Angular CLI también proporciona otros dos puntos de entrada para los flujos de trabajo de su biblioteca personalizada: ng add y ng update. Si no está familiarizado con estos comandos ng, puede obtener más información sobre ellos aquí y aquí. En una aplicación Angular que está usando su biblioteca, estos funcionan de manera similar al gancho postinstall de npm. Son llamados automáticamente por la CLI Angular, cuando se llama a

ng add my-custom-library

O

ng update my-custom-library

respectivamente.

Migration Schematics

Uno de los principales beneficios de usar la CLI de Angular es actualizar las dependencias de sus paquetes al tiempo que minimiza la necesidad de solucionar manualmente los cambios importantes o las obsolescencias. ¡Todo esto se puede automatizar definiendo esquemas de migración para su biblioteca!

Se ejecuta un esquema de migración cada vez que se agrega una versión más reciente de su biblioteca a la aplicación consumidora a través de ng update your-custom-library. En un esquema de migración, no solo puede definir qué cambios deben realizar los esquemas de migración, sino también especificar el ámbito de la migración (a qué versión afecta).

Adding migration schematics

La definición de esquemas de migración se realiza de forma similar a la definición de un esquema normal: debe crear una función que devuelva una regla. Esa regla puede manipular el árbol de trabajo, las cosas de registro y/o cualquier otra cosa que pueda hacer con Javascript. La parte más específica es asegurarse de que la CLI de Angular llame al esquema en el gancho de actualización ng.

Defining the schematics collection

En primer lugar, debe definir un archivo de collection.json esquemático. El nombre no importa. En el caso de nuestra biblioteca, lo hemos llamado migration-collection.json, ya que tenemos varias colecciones de esquemas y esto hace que sea más fácil saber cuál es cuál.

La estructura de tu collection.json debería tener un aspecto similar al siguiente:

{
    "schematics": {
        "migration-01": {
            //  Migration name, no strict naming, must be unique
            "version": "2.0.0", // The target version
                "description": "Updates my-custom-library from v1 to v2", // A short description, not mandatory
                "factory": "./update-2" // The update schematic factory
        }

        ,
        "migration-02": {
            "version": "3.0.0",
                "description": "Updates my-custom-library from v2 to v3",
                "factory": "./update-3"
        }

        ,

        ...
    }
}

El objeto schematics contiene todas las definiciones de schematics de actualización. Cada definición está bajo una propiedad con nombre (que tiene que ser única) y para cada una, debe especificar la versión en la que se introducen los "cambios" y la fábrica para el esquema que se ejecutará en el árbol de trabajo. El atributo version se utiliza para determinar cuándo se debe ejecutar el esquema.

Por ejemplo, supongamos que tienes una aplicación que consume my-custom-library@1.0.0. Con la definición de esquemas anterior, si ejecutara ng update my-custom-library@2.0.0, solo se ejecutaría el esquema "versión": "6.0.0" definido. Al correr

ng update my-custom-library@3.0.0

Se ejecutarían los esquemas de migración 2.0.0 y 3.0.0.

La definición real de los esquemas de migración (para v2.0.0, por ejemplo) está en ./update-2/index.ts puede ser como cualquier otro esquema. Una implementación muy básica sería esta:

export default function(): Rule {
  return (host: Tree, context: SchematicContext) => {
    const version = `1.0.0` // You can get this dynamically from the package.json
    context.logger.info(`Applying migration for custom library to version ${version}`);

    return host;
  };
}

Puede encontrar la definición de uno de los últimos esquemas de migración en igniteui-angular aquí.

Descargo de responsabilidad: En la implementación esquemática de nuestra biblioteca estamos haciendoun uso intensivodel servicio de lenguaje TypeScript para manipular archivos. Lamento no entrar en detalles, pero eso justificaría una publicación propia. Si tienes alguna pregunta, no dudes en ponerte en contacto con nosotros en los comentarios e intentaré responder lo mejor que pueda.

Adjuntar la colección de esquemas al gancho ng-update

Una vez que se crea el collection.json de migración y se definen los esquemas de migración, todo lo que queda es adjuntarlos correctamente al enlace ng-update. Todo lo que necesita hacer para eso es ir a la package.json de su biblioteca y agregar la siguiente propiedad "ng-update":

{
    "name": "my-custom-library",
    "version": "2.0.0",
    ... "ng-update": {
        "migrations": "./migrations/migration-collection.json"
    }
}

 

¡Eso es todo! Ahora, cada vez que alguien ejecuta ng update my-custom-library, la CLI de Angular y los esquemas que ha creado cuidadosamente se encargarán de cualquier cambio importante o deploración molesta que un usuario podría pasar por alto.

ng-add

El otro punto de entrada útil que proporciona la CLI de Angular es el enlace ng add. Cuando se define un esquema ng add, se ejecuta automáticamente en cuanto un usuario agrega la biblioteca a su proyecto de consumo mediante la ejecución de

ng add [custom-library]

Puedes pensar en ello como algo parecido al gancho postinstall de npm.

Definir un esquema ng add para su biblioteca es la mejor manera de asegurarse de que sus usuarios tengan una experiencia fácil por primera vez con él. A través de los esquemas, puede automatizar algunas configuraciones iniciales obligatorias, agregar/actualizar paquetes o simplemente registrar un gran "¡gracias!" a todos sus usuarios. 🙂

En nuestra biblioteca, hemos agregado un esquema ng add que instala nuestra CLI de IgniteUI en el espacio de trabajo del proyecto para que los usuarios puedan aprovechar al máximo nuestro conjunto de componentes a través de nuestra CLI.
Realizamos algunas transformaciones iniciales en el espacio de trabajo (agregando un archivo de .json personalizado necesario para que nuestra CLI se ejecute), agregamos algunos estilos y paquetes (para que nuestros componentes se rendericen correctamente) e incluso llamamos a algunos esquemas (¡schematiception!) desde nuestra CLI, donde hemos descargado algunas de las Angular lógica específica de la CLI.

Todo esto (¡y más!) se puede hacer automáticamente, simplemente llamando a ng add, que, en mi opinión, es el verdadero encanto de la Angular CLI.

Crear esquema ng-add

Para agregar un esquema ng add a su biblioteca, primero debe definirlo. Al igual que con cualquier otro esquema, debe formar parte de una colección. Si el proyecto ya expone esquemas, puede agregarlo a la colección existente con el nombre ng-add. Si no es así, puedes crear la colección desde cero:

En la carpeta raíz de la biblioteca:

mkdir schematics && cd schematics

echo blank > collection.json

mkdir ng-add

Abra el collection.json recién creado, modifíquelo para que apunte a la definición del esquema ng-add

{
    "$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
    "schematics": {
        "ng-add": {
            "description": "Installs the needed dependencies onto the host application.",
                "factory": "./ng-add/index",
                "schema": "./ng-add/schema.json"
        }
    }
}

En schematics/ng-add/index.ts puede crear la implementación del esquema ng-add tal como lo haría con cualquier otro esquema. Por ejemplo, para mostrar un simple mensaje de "¡Gracias!" a los usuarios, puede hacer lo siguiente:

export default function (options: Options): Rule {
	return (_tree: Tree, context: SchematicContext) => {
		context.logger.info(`Thank you for using our custom library! You're great!`);
	};
}

La implementación del esquema ng-add de IgniteUI Angular se puede encontrar aquí.

Incluir en package.json

Una vez que haya terminado con la implementación del esquema, debe incluir la definición de la colección en el package.json de la biblioteca. Si tu biblioteca ya expone una colección de esquemas, ¡lo tienes cubierto! De lo contrario, solo necesita agregar una propiedad "schematics", que apunte a la ubicación de su collection.json recién creado:

{
    "project": "my-custom-library",
    "version": "2.0.0",
    ... "schematics": "./schematics/collection.json"
}

Puede encontrar esta parte de la configuración reflejada en nuestro repositorio de biblioteca.

Bundling your schematics

Debe asegurarse de que los esquemas que ha definido (tanto las migraciones como las colecciones ng-add) se envíen correctamente con el paquete de biblioteca. Para ello, deberá definir una tarea de compilación independiente para los esquemas (ejecutada después de que se haya ejecutado la tarea de compilación principal), con outDir especificado para que apunte a la ubicación correcta en la carpeta dist del proyecto (de modo que los archivos collection.json tengan las mismas rutas, en relación con el package.json). Por último, deberá copiar explícitamente los archivos excluidos por el compilador (por ejemplo, cualquier archivo .json).

Suponiendo que el directorio de salida de los proyectos compilados es .. /dist (por lo que los archivos agrupados de su proyecto estarían bajo .. /dist/my-custom-lib/) la salida de compilación de tu esquema tendrá que ser .. /dist/schematics (para la colección de esquemas predeterminada, que contiene ng-add) y .. /dist/migrations (para la colección de esquemas de migración)

Para ello, primero debe definir un archivo de tsconfig.json para las colecciones de esquemas (ubicados en ./schematics/ o ./migrations, respectivamente). Por ejemplo, el contenido del archivo de la colección principal de esquemas (./schematics) sería algo como esto:

{
   "compilerOptions": {
	"target": "es6",
	"module": "commonjs",
	"sourceMap": false,
	"composite": true,
	"declaration": true,
	"outDir": "../../../dist/my-custom-lib/schematics/"
   }
}

A continuación, en la package.json del proyecto, defina un script que construya los esquemas y otro que copie los archivos:

{
   "name": "my-custom-library",
   ...
   "scripts": {
      "build:schematics": "tsc --project migrations/tsconfig.json",
      "copy:schematics:collection": "cp --parents migrations/*/collection.json ../../dist/my-custom-lib/"
   },
   ...
}

Lo mismo ocurre con las migraciones: un script separado para la compilación de TypeScript y para copiar los archivos.

Para el repositorio Ignite UI for Angular, puede consultar los vínculos para ver la implementación de la colección de esquemas predeterminada y las migraciones. (Dado que estamos usando gulp como herramienta de compilación, hemos definido tareas separadas allí para copiar los archivos collection.json)

Ejecución local de esquemas ng-add y ng-update

Antes de publicar el paquete de biblioteca con la nueva y brillante funcionalidad ng update y ng add, es posible que desee comprobar que los esquemas están realizando las transformaciones de trabajo adecuadas. Dado que, al final, ambas son solo implementaciones esquemáticas básicas, puede ejecutarlas como lo haría con cualquier otra: ¡usando ng g!

Después de compilar los archivos de biblioteca y los esquemas + migraciones, puede ir al directorio de salida especificado (donde se encuentra el package.json de su paquete) y empaquetarlo

npm pack

Running ng-add

Para comprobar el rendimiento de tu comando ng-add is dentro de un nuevo proyecto, puedes hacer lo siguiente:

Creación de un nuevo proyecto mediante la CLI de Angular

ng g my-test-project --routing=true

Una vez creado el proyecto, puede ir a la carpeta del proyecto e instalar su paquete manualmente desde el archivo .tgz:

npm i my-custom-library.tgz

Then, simply run

ng g my-custom-library:ng-add

Y revise el cambio en el lugar de trabajo una vez que esté terminado: ¡eso es lo que hará el ng-add de su paquete!

Running migrations

Para probar las migraciones, puede seguir los mismos pasos que los anteriores, aunque tendrá que especificar la ruta de acceso a la collection.json de esquemas de migración (ya que es diferente de la colección de esquemas predeterminada del proyecto).

Supongamos que el esquema de migración más reciente que desea probar se denomina update-1. Una vez que hayas instalado manualmente tu archivo .tgz, simplemente ejecuta:

ng g "./node_modules/my-custom-library/migration-collection.json:update-1"

De este modo, se aplicarán todos los cambios en el área de trabajo que aplicaría el esquema de migración más reciente.

Conclusiones

Con suerte, esta publicación le ha sido útil y le ha aclarado algunas cosas sobre la funcionalidad de adición y actualización ng de Angular CLI. Angular esquemas son ahora una parte sólida del ecosistema de sus proyectos y seguramente seguirán mejorando. Con cada vez​ ​más desarrolladores que los utilizan y crean conciencia sobre ellos, ahora es un buen momento para que las bibliotecas comiencen a adoptar esquemas. ¿Por qué no automatizar tanto usted como sus preocupaciones de usuarios? 🙂

Si tienes alguna pregunta, no dudes en ponerte en contacto con nosotros en los comentarios.

Thanks for reading!