Como escribir una libreria de TypeScript (para NPM)

Escribir código modular es una buena idea. Y nada es más modular que escribir una biblioteca. ¿Cómo se puede escribir una biblioteca TypeScript? Bueno, ¡de eso se trata exactamente este tutorial! Este tutorial funciona con TypeScript 5.x, TypeScript 4.x, TypeScript 3.x y TypeScript 2.x.

Paso 1: Configurar el tsconfig.json

Cree una carpeta de proyecto (con el nombre que desea), en este tutorial la llamaremos typescript-library. Creamos el tsconfig.json en /typescript-library. El tsconfig.json debería verse más o menos así:

_{typescript-library/tsconfig.json}

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es2019",
    "declaration": true,
    "outDir": "./dist"
  },
  "include": [
    "src/**/*"
  ]
}

Eso seria casi todo para un projecto que no seria una libreria, pero con una importante adicion: Necesitamos agregar el parametro "declaration": true. Esto generara los archivos .d.ts (tambien llamados archivos de declaracion) los cuales contienen los types de tu proyecto. De esta manera, si alguien esta utilizando tu libreria y tambien TypeScript, ellos obtendran los beneficios de typesafety y autocomplete!

Hablando de otras opciones, vamos a indagar rapidamente en estas: El module compiler option "module": "commonjs" es requerido si necesitas que tu liberia corra sin problemas en cualquier aplicacion de node.js. Reemplaza esto con "module": "esnext" si estas desarrollando un libreria para navegadores. "target": "es2015" especifica que tipo de version de javascript estaras utilizando. Esta debe de estar a la par con la version mas vieja de node.js (o del navegador) del cual quieras darle soporte. Elegir es2019 como compile target hace que tu libreria sea compatible con node.js 12.0 hacia delante. En 2023,este es un buen compromiso para transpilar a una versión moderna de JavaScript (que a su vez permite un mejor rendimiento, un código más conciso, etc.) y sigue dando soporte a versiones viejas de nodejs y navegadores. Si tu tienes una razón especifica para ir mas arriba (Se necesitan más funciones JS nativas de vanguardia en los archivos generados.) o mas abajo (Mas compatibilidad), necesitarias actualizar estos campos. Por ultimo, "outDir": "./dist" escribirá sus archivos compilados en la carpeta dist y la opción incluir especifica dónde reside su código fuente.

Paso 2: Implementa tus cambios

Proceda de la misma manera, como si no estuviera escribiendo una biblioteca. Cree una carpeta src y coloque allí todos los archivos fuente de su biblioteca (lógica de aplicación, datos y activos).

Para esta demostración, configuraremos un archivo tonto hello-world.ts, que se ve así:

_{typescript-library/src/hello-world.ts}

export function sayHello() {
  console.log('hi')
}
export function sayGoodbye() {
  console.log('goodbye')
}

Paso 3: Creando el index.ts

Agregue un archivo index.ts a su carpeta src. Su propósito es exportar todas las partes de la biblioteca que desea poner a disposición de los consumidores. En nuestro caso sería simplemente:

_{typescript-library/src/index.ts}

export {sayHello, sayGoodbye} from './hello-world'

El consumidor podrá utilizar la biblioteca más adelante así:

_{someotherproject/src/somefile.ts}

import {sayHello} from 'hwrld'
sayHello();

Verás que tenemos un nuevo nombre aquí, “hwrld”, que aún no hemos visto por ningún lado. ¿Cuál es este nombre? ¡Es el nombre de la biblioteca que vas a publicar en npm, también conocido como nombre del paquete!

Paso 4: Configura package.json

El nombre del paquete es lo que el consumidor utilizará para importar funciones de su biblioteca más adelante (muy importante poner un nombre que describa correctamente las funciones). Para esta demostración, elegí hwrld ya que todavía estaba disponible en npm. El nombre del paquete suele estar justo en la parte superior del package.json. Todo el package.json se vería así:

_{typescript-library/package.json}

{
  "name": "hwrld",
  "version": "1.0.0",
  "description": "Can log \"hello world\" and \"goodbye world\" to the console!",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "/dist"
  ]
}

Si aún no tienes un paquete, puede crear uno con npm init y lo guiará a través del proceso. Recuerda, el nombre del paquete que elija será utilizado por las personas para sus importaciones, ¡así que elije sabiamente!

También hay una bandera muy importante en este package.json: ¡Debes declarar dónde encontrar las declaraciones de tipo! Esto se hace usando “types”: “dist/index.d.ts” ¡De lo contrario, el consumidor no encontrará tu módulo!

Los archivos de propiedades finales le ayudan a incluir en la lista blanca los archivos que desea enviar al registro npm. ¡Esta suele ser una ruta mucho más fácil y segura que usar el archivo .npmignore!

Paso 5: Publicar en npm

Para finalizar utilizaremos estos comandos para poder publicar

tsc
npm publish

Si tiene un paquete con alcance, por ejemplo @myscope/mypackage, entonces necesita ejecutar npm publish –access=public, ya que la configuración predeterminada es privada y para ello necesita una cuenta paga.

¡Ahora estás listo para comenzar! Consume tu biblioteca donde quieras ejecutando:

npm install --save hwrld

Y consumelo usando

import {sayHello} from 'hwrld'
sayHello();

Para versiones posteriores, utiliza el principio semver. Cuando realizas un parche/corrección de errores en su biblioteca,  puedes usar npm version patch, para nuevas opciones en el paquete npm version minor y para cambios mayores npm version major.

Consulte la fuente completa de la biblioteca de demostración en github:

Fuente:

https://www.tsmean.com/articles/how-to-write-a-typescript-library