unbuild para TypeScript: guía completa con ejemplos prácticos

En el ecosistema actual de JavaScript y TypeScript, la compilación de proyectos es una de las tareas fundamentales. Los desarrolladores a menudo se enfrentan a la necesidad de configurar herramientas complejas como Webpack, Rollup o esbuild. La librería unbuild ofrece una solución elegante: un sistema de compilación unificado que combina las mejores prácticas y herramientas en una sola interfaz. No es solo otro compilador, sino un envoltorio unificado sobre esbuild y Rollup que determina automáticamente la estrategia de compilación óptima para tu proyecto.

El objetivo principal de unbuild es simplificar al máximo el proceso de compilación de librerías TypeScript. En lugar de pasar horas configurando archivos, el desarrollador obtiene una solución lista para usar. La librería genera automáticamente compilaciones CommonJS y ESM, crea declaraciones de tipos (d.ts), optimiza los bundles y soporta las características modernas de TypeScript. Esto convierte a unbuild en la opción ideal para autores de paquetes npm y proyectos open-source.

Unbuild es especialmente útil en los siguientes escenarios: creación de monorepositorios, compilación de librerías con soporte para tree-shaking, publicación de paquetes con código fuente TypeScript y migración desde compiladores antiguos. Gracias al soporte integrado para las exportaciones de package.json y la detección automática de puntos de entrada, la librería te permite centrarte en escribir código, no en configurar la infraestructura.

Instalación

Para instalar unbuild se utiliza el gestor de paquetes npm (o alternativas como yarn o pnpm). La librería se instala como dependencia de desarrollo:

npm install -D unbuild

O con yarn:

yarn add -D unbuild

Para pnpm:

pnpm add -D unbuild

Después de la instalación, se recomienda añadir un script de compilación en package.json:

{
  "scripts": {
    "build": "unbuild",
    "dev": "unbuild --watch"
  }
}

Inicio rápido

Vamos a crear un proyecto mínimo funcional. Estructura de archivos:

mi-libreria/
├── src/
│   └── index.ts
├── package.json
└── tsconfig.json

Contenido de src/index.ts:

export function saludar(nombre: string): string {
  return `¡Hola, ${nombre}!`;
}

export const version = '1.0.0';

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "declaration": true,
    "outDir": "./dist"
  },
  "include": ["src"]
}

Ahora ejecutamos la compilación:

npx unbuild

Después de la ejecución, en la carpeta dist aparecerán los siguientes archivos:

dist/index.mjs — Compilación ESM
dist/index.cjs — Compilación CommonJS
dist/index.d.ts — Declaraciones de tipos
dist/index.d.mts — Declaraciones para ESM

Unbuild crea automáticamente ambas compilaciones y genera las declaraciones de TypeScript. Para configurar las exportaciones en package.json, añade:

{
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  }
}