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

1. ¿Qué es tsup y para qué sirve?

tsup es un empaquetador (bundler) moderno, rápido y fácil de usar para TypeScript, construido sobre esbuild. Su objetivo principal es compilar tu librería TypeScript en uno o varios archivos listos para publicar en npm o usar en otros proyectos. A diferencia de configuraciones complejas como Webpack o Rollup, tsup ofrece una configuración "lista para usar" con cero configuración en la mayoría de los casos.

¿Para qué sirve tsup? Al desarrollar librerías en TypeScript, te enfrentas a varios desafíos: compilar TypeScript a JavaScript, generar declaraciones de tipos (.d.ts), combinar múltiples archivos en uno solo (bundle) para facilitar su uso, y hacerlo para diferentes formatos de módulos (CommonJS, ESM). tsup resuelve todo esto con un solo comando. Maneja automáticamente las importaciones, minimiza el código (opcional), genera source maps y soporta tree-shaking.

tsup es ideal para: crear paquetes npm, librerías de utilidades, componentes React/Vue, clientes API y cualquier otro proyecto que necesite una compilación rápida y sencilla de TypeScript. Gracias a esbuild, tsup es entre 10 y 100 veces más rápido que los empaquetadores tradicionales, lo que se nota especialmente en proyectos grandes.

2. Instalación

tsup se instala a través de npm o yarn como dependencia de desarrollo:

# npm
npm install --save-dev tsup

# yarn
yarn add --dev tsup

# pnpm
pnpm add --save-dev tsup

Después de la instalación, puedes ejecutar tsup usando npx o agregando un script en package.json.

3. Inicio rápido — ejemplo mínimo funcional

Vamos a crear una librería simple y compilarla con tsup.

Paso 1: Crea el archivo src/index.ts:

// src/index.ts
export function saludar(nombre: string): string {
    return `¡Hola, ${nombre}! Bienvenido a tsup.`;
}

export function sumar(a: number, b: number): number {
    return a + b;
}

Paso 2: Crea el archivo de configuración tsup.config.ts (o usa argumentos de línea de comandos):

// tsup.config.ts
import { defineConfig } from 'tsup';

export default defineConfig({
    entry: ['src/index.ts'],        // punto de entrada
    format: ['cjs', 'esm'],         // formatos de salida
    dts: true,                      // generar archivos .d.ts
    splitting: false,               // no dividir en fragmentos
    sourcemap: true,                // generar source maps
    clean: true,                    // limpiar la carpeta dist antes de compilar
});

Paso 3: Agrega el script en package.json:

{
    "scripts": {
        "build": "tsup"
    }
}

Paso 4: Ejecuta la compilación:

npm run build

El resultado aparecerá en la carpeta dist/:

dist/
├── index.js          (CommonJS)
├── index.mjs         (ESM)
├── index.d.ts        (declaraciones de tipos)
├── index.d.mts       (declaraciones para ESM)
└── index.js.map      (source map)

4. Métodos/funciones/clases principales

tsup no tiene clases en el sentido tradicional. Su API principal es la función defineConfig y un objeto de configuración. A continuación, las 8 opciones clave de configuración.

4.1. `entry`

Firma: entry: string | string[] | Record<string, string>

Define los archivos de entrada que tsup debe empaquetar. Puede ser un solo archivo, un array de archivos o un objeto con nombres personalizados.

// Ejemplos de entry
entry: ['src/index.ts'],
entry: ['src/index.ts', 'src/cli.ts'],
entry: {
    main: 'src/index.ts',
    cli: 'src/cli.ts',
},

4.2. `format`

Firma: format: ('cjs' | 'esm' | 'iife')[]

Especifica los formatos de módulo de salida. tsup puede generar múltiples formatos simultáneamente.

// Formatos disponibles
format: ['cjs'],           // Solo CommonJS
format: ['esm'],           // Solo ES Modules
format: ['cjs', 'esm'],    // Ambos formatos
format: ['iife'],          // Formato para navegadores

4.3. `dts`

Firma: dts: boolean | { entry?: string; resolve?: boolean }

Genera archivos de declaración de tipos (.d.ts) para tu librería. Esencial para que los consumidores de tu paquete tengan autocompletado y verificación de tipos.

// Generar declaraciones de tipos
dts: true,

// Configuración avanzada
dts: {
    entry: 'src/index.ts',
    resolve: true,
},

4.4. `splitting`

Firma: splitting: boolean

Controla si tsup divide el código en múltiples fragmentos (chunks). Útil para aplicaciones grandes, pero generalmente se desactiva en librerías.

// Desactivar división (recomendado para librerías)
splitting: false,

// Activar división (útil para aplicaciones)
splitting: true,

4.5. `sourcemap`

Firma: sourcemap: boolean | 'inline' | 'external'

Genera source maps para facilitar la depuración del código compilado.

// Source maps externos (archivos .map separados)
sourcemap: true,

// Source maps incrustados en el mismo archivo
sourcemap: 'inline',

// Sin source maps
sourcemap: false,

4.6. `clean`

Firma: clean: boolean

Limpia la carpeta de salida antes de cada compilación para evitar archivos residuales.

// Limpiar antes de compilar
clean: true,

4.7. `minify`

Firma: minify: boolean

Minifica el código de salida para reducir el tamaño del archivo. Ideal para producción.

// Minificar el código
minify: true,

// Sin minificar (por defecto)
minify: false,

4.8. `target`

Firma: target: string | string[]

Especifica la versión de ECMAScript de salida. tsup convertirá el código para que sea compatible con el entorno objetivo.

// Compatible con Node.js 14+
target: 'node14',

// Múltiples objetivos
target: ['es2020', 'node14'],

// Por defecto (esnext)
target: 'esnext',

5. Ejemplo completo: librería de utilidades

Veamos un ejemplo más completo de una librería de utilidades con múltiples puntos de entrada.

Estructura del proyecto:

mi-libreria/
├── src/
│   ├── index.ts
│   ├── math.ts
│   └── string.ts
├── tsup.config.ts
├── package.json
└── tsconfig.json

Contenido de los archivos:

// src/math.ts
export const PI = 3.14159;
export function areaCirculo(radio: number): number {
    return PI * radio * radio;
}

// src/string.ts
export function capitalizar(texto: string): string {
    return texto.charAt(0).toUpperCase() + texto.slice(1);
}
export function invertir(texto: string): string {
    return texto.split('').reverse().join('');
}

// src/index.ts
export * from './math';
export * from './string';

Configuración de tsup:

// tsup.config.ts
import { defineConfig } from 'tsup';

export default defineConfig({
    entry: ['src/index.ts'],
    format: ['cjs', 'esm'],
    dts: true,
    splitting: false,
    sourcemap: true,
    clean: true,
    minify: true,
    target: 'es2020',
});

Al ejecutar npm run build, tsup generará los archivos compilados y optimizados en la carpeta dist/.

6. Conclusión

tsup es una herramienta esencial para cualquier desarrollador TypeScript que quiera crear librerías modernas y eficientes. Su simplicidad, velocidad y flexibilidad lo convierten en la opción ideal frente a alternativas más complejas. Con una configuración mínima, puedes compilar, empaquetar y publicar tu código TypeScript en múltiples formatos, con declaraciones de tipos y source maps incluidos.

Empieza a usar tsup hoy y simplifica tu flujo de trabajo de desarrollo de librerías TypeScript. ¡Tu futuro yo te lo agradecerá!