unbuild y tsdown: las opciones modernas y el stub mode

Si tsup definió la generación anterior de empaquetadores de librerías, dos herramientas se reparten la moderna. unbuild viene del ecosistema UnJS y trae una idea que cambia el bucle de trabajo: un stub mode que te deja desarrollar la librería sin reconstruirla en cada guardado. tsdown viene del mundo de Rolldown y Oxc, y trae la promesa del motor en Rust aplicada por fin al empaquetado de librerías, no solo al de aplicaciones. Conocer ambas no es coleccionar herramientas: es entender las dos direcciones en que ha evolucionado el problema —la ergonomía del bucle de desarrollo y la velocidad bruta del motor— y saber cuál te resuelve el día a día.

unbuild y la inferencia desde exports

unbuild parte de una observación fina: la mayor parte de la configuración de un empaquetador ya está escrita en tu package.json. Los campos exports, main y module declaran qué expone tu librería y en qué formato; repetir esa información en un archivo de build es duplicarla y arriesgarse a que diverjan. Por eso unbuild puede inferir sus entradas y sus formatos directamente de esos campos, y funcionar casi sin configuración propia.

Cuando necesitas control, la configuración vive en un build.config.ts explícito. unbuild se apoya en Rollup para el bundling y en mkdist para el modo archivo a archivo, y expone ambos bajo una misma interfaz:

// build.config.ts
import { defineBuildConfig } from "unbuild";

export default defineBuildConfig({
  entries: ["src/index"],
  declaration: true,
  rollup: { emitCJS: true },
});

• entries: los puntos de entrada; si los omites, unbuild los deduce de exports.
• declaration: genera los .d.ts junto al código.
• emitCJS: añade la salida CommonJS además del ESM por defecto.
• mkdist: un modo alternativo que transpila archivo a archivo sin empaquetar.

El stub mode: no reconstruir en desarrollo

La aportación más original de unbuild es el stub mode, y para apreciarla hay que ver el problema que resuelve. Cuando desarrollas una librería y la pruebas desde otro paquete —en un monorepo, por ejemplo—, cada cambio en el código de la librería exige reconstruir su dist para que el consumidor vea la versión nueva. Ese bucle de reconstruir y probar, repetido cientos de veces al día, es una fricción constante.

El stub mode lo elimina. Al ejecutar unbuild --stub, en vez de compilar tu código, unbuild escribe en dist un archivo diminuto —un stub— que reexporta tu código fuente cargándolo en vivo a través de jiti, un runtime que transpila TypeScript al vuelo. El consumidor importa dist como siempre, pero lo que recibe es tu src actual, sin build de por medio. Editas el fuente, guardas, y el cambio ya está: no hay reconstrucción porque no hay artefacto compilado que reconstruir.

tsdown sobre Rolldown

tsdown es la otra dirección: no reinventa el bucle de desarrollo, sino que lleva el motor en Rust al empaquetado de librerías. Está construido sobre Rolldown —el bundler en Rust, sobre Oxc— y su propuesta es la coherencia final del toolchain de 2026: el mismo motor que Vite 8 usa para aplicaciones, ahora afinado para publicar paquetes. De ahí que el ecosistema de tsup lo señale como su sucesor natural: misma ergonomía de cero configuración, pero sin la costura de dos motores.

Su configuración se lee casi igual que la de tsup, lo cual es deliberado para suavizar la migración, pero con una diferencia decisiva bajo el capó: las declaraciones de tipos no viajan en una pasada lenta con un comprobador aparte, sino que se apoyan en isolatedDeclarations de TypeScript, lo que permite emitirlas sin la inferencia completa entre archivos y a una velocidad acorde con el resto del build.

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

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

flowchart TD
MOD[empaquetadores modernos] --> UN[unbuild del ecosistema UnJS]
MOD --> TD[tsdown sobre Rolldown y Oxc]
UN --> INF[infiere entradas desde exports]
UN --> STUB[stub mode carga el fuente con jiti]
TD --> RUST[motor en Rust unifica codigo y tipos]
TD --> SUC[sucesor senalado de tsup]

El modo sin bundle: mkdist

unbuild no solo empaqueta con Rollup; trae también mkdist, un modo que transpila archivo a archivo sin fundir el grafo. Cada archivo de tu src se convierte en un archivo de dist, conservando la estructura, e incluso copia y procesa activos como bloques de estilo junto al código. Es la respuesta de unbuild al empaquetado transpile-only, y se declara como una entrada más dentro de la configuración.

// build.config.ts con una entrada mkdist sin bundle
import { defineBuildConfig } from "unbuild";

export default defineBuildConfig({
  entries: [
    { builder: "mkdist", input: "src", outDir: "dist" },
  ],
  declaration: true,
});

La diferencia con el modo Rollup de la misma herramienta es exactamente el eje empaquetar o no empaquetar que recorre todo este nivel. El builder de Rollup funde tu grafo en pocos archivos; el builder mkdist lo preserva módulo a módulo. Que unbuild ofrezca los dos bajo una sola configuración es su forma de decir que la elección no es de herramienta sino de forma de salida, y que una misma librería puede querer una cosa u otra según lo que exponga.

Esa flexibilidad es más útil de lo que parece: puedes empaquetar la entrada principal para dar un artefacto limpio y, a la vez, publicar sin bundle un conjunto de utilidades para que el consumidor las importe sueltas, todo desde el mismo build.config.ts.

• builder: mkdist: transpila archivo a archivo, sin bundle, preservando el árbol.
• builder: rollup: funde el grafo en pocos artefactos, el modo empaquetado.
• Activos junto al código: mkdist copia y procesa recursos que viven al lado de los módulos.
• Una config, dos formas: combinas entradas empaquetadas y sin bundle en el mismo build.

Y como unbuild lee el package.json, las entradas se anuncian solas: el mismo exports que consume el usuario es el que la herramienta usa para saber qué construir, sin duplicar nada.

{
  "exports": {
    ".": "./dist/index.mjs",
    "./utils": "./dist/utils.mjs"
  }
}

La elección entre los dos builders se puede resumir en una línea por escenario:

• Entrada única y cerrada: el builder Rollup, que empaqueta el grafo.
• Muchas subrutas: el builder mkdist, que preserva el árbol de módulos.
• Activos junto al código: mkdist, que los copia y procesa al lado.
• Inferencia total: deja que exports dicte las entradas y no configures apenas nada.