Elegir la herramienta y decidir: empaquetar o publicar sin bundle

Llegas al final del nivel con cuatro herramientas en la mano y una duda legítima: ¿cuál uso? Pero antes de esa pregunta hay otra más honda que casi nadie plantea y que condiciona la respuesta entera: ¿debo empaquetar mi librería, o publicarla sin bundle, archivo a archivo? La elección de la herramienta es táctica y reversible; la de empaquetar o no es arquitectónica y le dice a tus consumidores cómo pueden importar tu código, hasta qué punto pueden podarlo y cómo lo van a depurar. Este capítulo cierra el nivel poniendo esas dos decisiones en su orden correcto: primero la naturaleza del artefacto, después la herramienta que lo produce.

El eje empaquetar o no empaquetar

La primera decisión no es qué herramienta, sino qué forma quieres que tenga tu salida. Empaquetar significa recorrer el grafo y fundir tus muchos módulos en uno o pocos archivos, aplicando tree shaking y ocultando la estructura interna. Publicar sin bundle —el modo transpile-only, también llamado unbundled— significa transpilar cada archivo fuente a su archivo de salida, uno a uno, preservando el árbol de módulos tal cual lo escribiste.

Cada opción es un contrato distinto con quien te consume. El bundle entrega un artefacto cerrado y afinado: menos archivos, sin rastro de tu organización interna, con el tree shaking ya aplicado. El unbundled entrega tu estructura abierta: el consumidor puede importar un submódulo concreto —un deep import como mi-lib/utils— sin arrastrar el resto, su bundler ve módulos pequeños y granulares sobre los que hace su propio tree shaking con precisión, y los sourcemaps apuntan a archivos que se corresponden con los tuyos, lo que facilita depurar.

• Empaquetar: uno o pocos archivos, estructura oculta, tree shaking hecho por ti, ideal para un distribuible cerrado.
• Transpile-only: un archivo por módulo, estructura preservada, deep imports habilitados, tree shaking delegado al consumidor.
• preserveModules: la opción de Rollup y Rolldown que emite sin fundir, conservando el grafo.
• mkdist y tsc: transpilan archivo a archivo por naturaleza, sin construir un bundle.

La matriz de decisión

Con el eje claro, la elección de herramienta casi se deduce del tipo de librería. Una utilidad pequeña y autocontenida se beneficia de empaquetar: un tsdown o un tsup producen un artefacto limpio en segundos. Una librería grande con muchos puntos de entrada —un design system, una colección de utilidades donde el consumidor solo quiere una— pide transpile-only, para que cada deep import cueste solo lo que importa. Una librería de componentes con CSS reclama Vite en lib mode por su procesado de assets. Y un paquete del estilo UnJS, que quiere iterar sin reconstruir, encuentra en unbuild y su stub mode su bucle natural.

// tsdown sin bundle: preserva el arbol de modulos
import { defineConfig } from "tsdown";

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

Recomendación para 2026

Con el ecosistema de 2026 sobre la mesa, la recomendación se puede afinar sin caer en el dogma. Para una librería de TypeScript nueva y sin assets, tsdown sobre Rolldown es el punto de partida por defecto: hereda el motor en Rust del resto del toolchain, genera tipos con isolatedDeclarations sin la pasada lenta, y el propio ecosistema de tsup lo señala como relevo. Para una librería de componentes con CSS, Vite en lib mode sigue siendo la respuesta por su procesado de assets. Para el flujo UnJS, unbuild y su stub. Y tsup, aunque cede la frontera del rendimiento, sigue siendo una elección perfectamente válida para lo que ya funciona.

Sobre el eje del bundle, la regla práctica es: empaqueta las librerías pequeñas y autocontenidas, y publica sin bundle las grandes con muchas entradas. En caso de duda, el unbundled preservando módulos es la opción más respetuosa con el consumidor, porque le deja a él las decisiones de poda en vez de tomarlas por él.

Cuando publicas sin bundle, el exports suele apoyarse en comodines para no listar cada archivo a mano, dejando que un solo patrón cubra todas las subrutas del árbol:

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

Ese comodín es lo que convierte un árbol de módulos en un conjunto de deep imports usables sin escribir una entrada por archivo. Con él, cada módulo que emitas queda disponible como subruta de forma automática, y el consumidor importa exactamente lo que necesita.

• Utilidad pequeña: empaqueta; un artefacto cerrado basta y sobra.
• Design system: sin bundle; el consumidor importa solo los componentes que use.
• Componentes con CSS: Vite en lib mode por su procesado de assets.
• Iteración local intensa: unbuild con stub para no reconstruir en cada cambio.
• Preset o plugin compartido: empaqueta; una entrada única simplifica el consumo.
• Muchos consumidores dispares: publica dual y sin bundle, la superficie más flexible.

flowchart TD
Q[que tipo de libreria publicas] --> P[utilidad pequena autocontenida]
Q --> G[libreria grande con muchas entradas]
Q --> C[componentes con CSS]
Q --> U[flujo UnJS con iteracion local]
P --> B[empaquetar con tsdown o tsup]
G --> T[transpile only preservando modulos]
C --> V[Vite en lib mode]
U --> N[unbuild con stub mode]

Preservar módulos: cómo se ve sin bundle

Publicar sin bundle tiene un nombre técnico en Rollup y Rolldown: preserveModules. En vez de fundir el grafo, el bundler transpila cada módulo a su propio archivo de salida y conserva la estructura de carpetas, de modo que el dist es un espejo de tu src pero en JavaScript ya emitido. Es el mecanismo que hace posible el deep import, porque para que el consumidor pueda pedir mi-lib/utils esa ruta tiene que existir como archivo real en el paquete.

// rolldown o rollup preservando el arbol de modulos
export default {
  input: "src/index.ts",
  output: {
    dir: "dist",
    format: "es",
    preserveModules: true,
    preserveModulesRoot: "src",
  },
};

La consecuencia más importante es para el tree shaking del consumidor. Cuando tu librería llega como un solo bundle, el bundler de la aplicación tiene que analizar ese archivo grande para decidir qué sobra; cuando llega como módulos granulares, la poda es casi trivial, porque cada import trae solo su archivo y sus dependencias directas. Por eso los design systems y las librerías de utilidades grandes casi siempre se publican sin bundle: maximizan lo que el consumidor puede dejar fuera.

• preserveModules: emite un archivo por módulo en vez de fundir el grafo.
• preserveModulesRoot: fija la raíz para que el dist no arrastre la ruta src.
• Deep imports: cada módulo es un archivo, así que las subrutas existen de verdad.
• Tree shaking fino: el consumidor poda por archivo, sin analizar un bundle monolítico.

El coste es simétrico y hay que nombrarlo. Sin bundle publicas muchos más archivos, el exports se vuelve más grande —o usas un patrón con comodines para no listarlos uno a uno—, y pierdes las optimizaciones que solo son posibles cuando el bundler ve todo el grafo junto, como inlinear una función privada que se usa una sola vez. No hay opción gratis: el bundle optimiza a cambio de cerrar; el unbundled abre a cambio de no optimizar entre archivos.