tsup sobre esbuild: configuración mínima y su reinado

Durante buena parte de la última década, empaquetar una librería de TypeScript era un ejercicio de configuración: un rollup.config.js con media docena de plugins, o un webpack que nadie quería tocar. tsup llegó con una tesis distinta —que el caso común no debería necesitar configuración alguna— y la cumplió apoyándose en esbuild para ir rápido. Una sola línea, tsup src/index.ts, y ya tienes un bundle. Esa promesa de cero configuración, servida a la velocidad de Go, explica por qué tsup se volvió el pavimento por defecto sobre el que se publicaron miles de paquetes, y también por qué su límite está exactamente donde esbuild deja de alcanzar.

Configuración mínima

La tesis de tsup es que empaquetar una librería sencilla no debería costar más que nombrar el punto de entrada. Todo lo demás —el formato, el target, el tree shaking— trae un valor por defecto sensato que puedes no tocar nunca. En su forma más pura, tsup es un comando:

# Un bundle a partir de un unico punto de entrada
tsup src/index.ts

# Varios formatos y declaraciones, todavia sin archivo de config
tsup src/index.ts --format esm,cjs --dts

Cuando el proyecto crece, la misma configuración se muda a un tsup.config.ts tipado, sin cambiar de modelo mental. Cada bandera del comando tiene su campo equivalente, y defineConfig te da el autocompletado:

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

export default defineConfig({
  entry: ["src/index.ts"],
  format: ["esm", "cjs"],
  dts: true,
  clean: true,
  sourcemap: true,
  treeshake: true,
});

• entry: uno o varios puntos de entrada; cada uno produce su propio artefacto.
• format: el array de formatos; esm y cjs cubren a casi todos los consumidores.
• dts: activa la generación de declaraciones en una pasada separada.
• clean: vacía el directorio de salida antes de cada build para no dejar restos.

Múltiples formatos en una pasada

El punto donde tsup ahorra más trabajo es el paquete dual. Pedir --format esm,cjs produce, del mismo grafo, un .mjs para los consumidores de ESM y un .cjs para el Node clásico, con las extensiones correctas y sin que orquestes dos builds. Añade --dts y obtienes además un .d.ts que sirve a ambos. Con tres banderas cubres la superficie de distribución que en Rollup exigía un output como array y un plugin de declaraciones cableado a mano.

Esa comodidad descansa en una arquitectura de dos motores que conviene ver con claridad. El código —transpilar TypeScript, resolver el grafo, aplicar tree shaking, minificar— lo hace esbuild, y de ahí viene la velocidad. Pero esbuild no comprueba tipos: no sabe inferir el tipo de una expresión ni, por tanto, emitir un .d.ts correcto. Así que tsup delega esa tarea en una pasada aparte, apoyada en Rollup y rollup-plugin-dts, que lee tus tipos y los empaqueta en un único archivo de declaraciones.

El reparto de trabajo entre los dos motores es nítido, y explica exactamente dónde se va el tiempo del build cuando el proyecto crece:

• esbuild: transpila, resuelve el grafo, hace tree shaking y minifica el código.
• Rollup: empaqueta las declaraciones que esbuild no sabe generar.
• La velocidad: nace en esbuild y domina el tiempo del código.
• El cuello de botella: es la pasada de tipos, de otro orden de magnitud.
• La consecuencia: el mismo build sin --dts compila casi al instante.

Por qué reinó y quién lo releva

tsup se volvió el estándar de facto por una combinación difícil de batir en su momento: cero configuración para el caso común, velocidad de esbuild para el código, y salida dual con tipos en un solo comando. Entre 2021 y 2025, si abrías un paquete de TypeScript publicado en npm, lo más probable es que detrás hubiera un tsup. Su ergonomía marcó el listón de lo que la gente esperaba de un empaquetador de librerías.

Pero la misma costura que lo define —esbuild rápido para el código, un motor más lento para los tipos— es la que abre la puerta a su relevo. En 2026, el empuje de Rolldown y Oxc permite un empaquetador que unifica ambas mitades bajo un motor en Rust, y el propio ecosistema de tsup señala a tsdown como el camino natural de migración. tsup no desaparece ni deja de funcionar; sencillamente deja de ser la frontera del rendimiento, igual que Rollup dejó de serlo cuando llegó Rolldown.

flowchart LR
SRC[tu codigo TypeScript] --> ES[esbuild transpila y empaqueta]
SRC --> DTS[pasada aparte para los tipos]
ES --> JS[salida esm y cjs rapida]
DTS --> RD[Rollup empaqueta las declaraciones]
RD --> OUT[un archivo de tipos]
JS --> BUN[bundle listo]

Las banderas que de verdad usarás

Más allá del caso mínimo, un puñado de opciones cubren casi todo lo que una librería necesita afinar, y conviene conocerlas porque son las que separan un artefacto correcto de uno descuidado. El target fija la sintaxis de salida —qué versión de JavaScript emites—; minify decide si comprimes; sourcemap adjunta los mapas para depurar; splitting permite trocear el ESM en fragmentos compartidos; y treeshake poda lo que no se use antes de emitir.

// tsup.config.ts con las opciones habituales de una libreria
import { defineConfig } from "tsup";

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

Dos matices importan para una librería. El primero: rara vez querrás minify: true en un paquete que otros van a re-empaquetar, porque su bundler ya minificará la aplicación final y una librería minificada solo dificulta leer los sourcemaps. El segundo: splitting solo aplica al formato esm; el cjs no soporta la carga dinámica de fragmentos que el troceado necesita. Y para el bucle de desarrollo, --watch reconstruye al guardar, con un onSuccess opcional que ejecuta un comando tras cada build correcto.

Merece la pena interiorizar que estos valores por defecto no son neutrales: son la postura de tsup sobre qué es una librería sana. Publicar sin minificar, con sourcemaps y con tree shaking activo es lo que un consumidor espera, y tsup te lo da sin pedírselo.

• target: la versión de JavaScript de salida; deja que el consumidor baje más si lo necesita.
• minify: normalmente false en librerías; minifica quien construye la app final.
• splitting: trocea el esm en fragmentos compartidos; no aplica al cjs.
• sourcemap: adjunta los mapas para que el consumidor pueda depurar tu código.
• --watch: reconstruye al guardar, el modo para iterar sobre la propia librería.
• onSuccess: ejecuta un comando tras cada build correcto, útil para encadenar validaciones.