Cómo empaquetar una librería TypeScript para npm y reutilizarla en otros proyectos

Reutilizar código es esencial para desarrollar aplicaciones mantenibles y escalables. Una de las formas más eficientes de lograrlo en TypeScript es mediante la creación de un paquete para npm, lo que permite importar tu librería en distintos proyectos sin la necesidad de copiar archivos manualmente. En esta entrada veremos cómo empaquetar tu librería TypeScript para distribuirla como un paquete npm, facilitando así su instalación e integración en otros proyectos.

En una serie anterior explicamos cómo crear una librería TypeScript con Webpack, lo que nos permitió generar código optimizado para su uso en navegadores. Basándonos en este proyecto, ahora vamos a dar un paso más y empaquetar esta misma librería para distribuirla como un paquete de npm, de modo que pueda ser instalada e importada fácilmente en otros proyectos.

Descarga de la librería tstlane como base

En este proyecto, utilizaremos como punto de partida la versión 1.3 de tstlane, la plantilla actualizada resultante de nuestra serie sobre creación de librerías TypeScript.

Actualización de dependencias

Antes de empaquetar la librería, es recomendable actualizar todas las dependencias para contar con las versiones más recientes y seguras. Para ello, podemos utilizar la herramienta npm-check-updates. Solo es necesario instalarla de manera global y ejecutar los siguientes comandos en el proyecto:

ncu -u
npm install

El comando ncu -u actualizará todas las dependencias en el archivo package.json. A continuación. npm install instalará las nuevas dependencias el proyecto.

Creación de archivos de índices diferenciados

Cuando una librería se utiliza tanto en navegadores como en entornos Node.js, es importante definir puntos de entrada diferenciados para cada contexto. Pudiendo usar configuraciones diferrentes en cada caso. Para ello, crearemos dos archivos:

• index-bundle.ts: Punto de entrada para Webpack.
• index.ts: Punto de entrada para npm.

Archivo index-bundle.ts

Este archivo incluirá información adicional (por ejemplo, la versión y el hash de compilación) para facilitar la depuración y el control de versiones:

declare const VERSION: string;
declare const HASH: string;

export const version = {
  version: VERSION,
  build: HASH,
};

export * from './index';

En este archivo se declaran y exportan las constantes VERSION y HASH, lo que nos permite identificar respectivamente la versión y el hash de compilación a la hora de usar la libreria. A continuación, se importa y reexporta todo lo definido en index.ts.

Archivo index.ts

Este será el punto de entrada principal que reexporta los módulos de la librería:

export * as array from './array';

De esta forma, al desarrollar nuevos submódulos, solo será necesario modificar el index.ts, manteniendo separados los detalles específicos para cada entorno.

Empaquetado de la librería

Una vez reestructurado el código, podemos empaquetar en un archivo .tgz que podremos instalar en otros proyectos mediante npm.

Pasos para empaquetar la librería

En primer lugar, vamos a ver cómo se puede realizar el proceso de forma manual, para más tarde crear un script que pueda automatizara completamente el proceso. Los pasos para crear el paquete son:

1. Limpiar el directorio de compilación: Antes de volver a compilar, es aconsejable eliminar la carpeta dist para evitar incluir archivos innecesarios. En Linux o Mac esto se puede hacer con:

rm -rf dist

2. Compilar el código TypeScript: Usamos el compilador de TypeScript para generar la versión final del código:

npx tsc

O mejor, se puede recurrir al script creado en package.json de proyecto tslane:

npm run build

3. Crear un archivo package.json específico para el paquete: Dentro de la carpeta dist, debemos incluir un package.json con las configuraciones adecuadas.
4. Empaquetar el código en un archivo .tgz: Esto se consigue con el comando pack de npm.

npm pack

Esto generará un archivo .tgz listo para ser publicado o instalado en otros proyectos.

Automatización del proceso

Para evitar repetir manualmente todos estos pasos cada vez que se necesita empaquetar la librería, podemos crear un proceso para que lo haga todo automáticamente. En primer lugar se puede crear un script para que cree el archivo package.json, a continuación se puede crear el script npm.

Script para generar package.json en dist

Este script actualiza el package.json, eliminando las configuraciones innecesarias y ajustando las rutas para el paquete:

const fs = require('fs');

// Leer el package.json del proyecto
const packageData = require('./package.json');

// Actualizar valores
packageData.main = './index.js';
packageData.types = './index.d.ts';
packageData.module = './index.js';

delete packageData.files;
delete packageData.devDependencies;
delete packageData.scripts.pack;

// Guardar el nuevo package.json en la carpeta dist
const data = JSON.stringify(packageData, null, 2);
fs.writeFileSync('./dist/package.json', data);

// Copiar el README.md a la carpeta dist
fs.copyFileSync('./README.md', 'dist/README.md');

Este script:

• Crea un package.json limpio en dist
• Elimina dependencias innecesarias
• Copia el README.md

Automatización con npm scripts

Podemos instalar del-cli para facilitar la limpieza del directorio dist:

npm install --save-dev del-cli

Luego, en package.json, añadimos un nuevo script que implementa todos los pasos descritos anteriormente:

"scripts": {
  "pack": "npx del-cli ./dist && npm run build && node prepack && cd dist && npm pack && cd .."
}

Ahora, empaquetar la librería es tan sencillo como ejecutar:

npm run pack

Esto eliminará dist, compilará la librería, generará el package.json, copiará los archivos necesarios y ejecutará npm pack.

Publicación y uso del paquete

Una vez generado el archivo .tgz, podemos instalarlo en otros proyectos sin necesidad de publicarlo en npm:

npm install ./tstlane-1.4.0.tgz

Si queremos publicarlo en npm, simplemente ejecutamos:

npm publish --access public

Esto hará que el paquete esté disponible para su instalación con:

npm install tstlane

Conclusiones

Empaquetar una librería TypeScript para npm es un proceso sencillo que, si se estructura correctamente, permite:

• Modularidad: Separar los puntos de entrada para Webpack y npm mejora la compatibilidad.
• Automatización: La creación de scripts reduce errores y ahorra tiempo.
• Reutilización: Un paquete bien configurado se integra fácilmente en otros proyectos, facilitando el mantenimiento y la escalabilidad.

Con estos pasos, podrás empaquetar y distribuir tu librería de forma eficiente, asegurando que siempre estés trabajando con la versión más optimizada y fácil de mantener.

Como es habitual, los cambios al proyecto se publicarán en el repositorio tslane de nuestra cuenta de GitHub.

Nota: La imagen de este artículo fue generada utilizando un modelo de inteligencia artificial.