Crear bundles con Rollup y tsup para bibliotecas

La configuración predeterminada de Vite está optimizada para aplicaciones: empaqueta todo, gestiona los recursos y genera un index.html. Para una biblioteca de componentes necesita una salida diferente: archivos JavaScript ESM/CJS puros, sin sobrecarga en tiempo de ejecución, sin incluir React en el paquete y con declaraciones de TypeScript adecuadas. El modo de biblioteca de Vite funciona, pero Rollup y tsup están más orientados a este propósito.

Rollup ha sido el empaquetador estándar para bibliotecas de JavaScript durante años. Produce una salida limpia y eficiente, con una excelente eliminación de código no utilizado, y admite los formatos de salida ESM y CJS. El scope hoisting de Rollup elimina la sobrecarga de los envoltorios de módulos y produce los paquetes de biblioteca más pequeños posibles.

tsup es un empaquetador de TypeScript sin configuración basado en esbuild. Es considerablemente más rápido que Rollup (esbuild compila en microsegundos, frente a los milisegundos de Rollup). La configuración mínima: { entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true } produce automáticamente ambos formatos de módulo y las declaraciones de TypeScript.

Las opciones principales de tsup son: entry es la matriz de archivos de entrada. format especifica los formatos de salida: ['esm', 'cjs']. dts: true genera archivos de declaración de TypeScript .d.ts junto con la salida JS. target establece el entorno mínimo de JavaScript (esnext o es2020). splitting: false mantiene la salida en archivos individuales.

esbuild (mediante tsup) compila entre 10 y 100 veces más rápido que Rollup. Rollup genera una salida ligeramente más optimizada, con una granularidad de tree-shaking superior y más control sobre los límites de los chunks. Para la mayoría de las bibliotecas de componentes, la velocidad de tsup resulta más conveniente durante el desarrollo. Para obtener el máximo control sobre el tree-shaking o trabajar con configuraciones complejas de múltiples entradas, se prefiere Rollup.

La configuración más importante del empaquetador para una biblioteca de React es la siguiente: no incluya nunca React ni ReactDOM en el bundle. Márquelos como externos para excluirlos de la salida. Si su biblioteca incluye React en el bundle, los consumidores terminarán con dos copias de React: una de su bundle y otra de su aplicación. Esto rompe todos los hooks de React debido a la existencia de varias instancias de React.

En la configuración de tsup, use la opción external: external: ['react', 'react-dom']. En la configuración de Rollup, establezca external: ['react', 'react-dom', 'react/jsx-runtime']. Incluya react/jsx-runtime si su biblioteca utiliza JSX Transform. Marque también como externas las demás peer dependencies que declare su biblioteca.

Una configuración mínima de Rollup para una biblioteca de TypeScript requiere tres plugins: @rollup/plugin-typescript para compilar TypeScript, @rollup/plugin-node-resolve para resolver las importaciones de node_modules y @rollup/plugin-commonjs para convertir las dependencias CommonJS a ESM en el bundle. Añada rollup-plugin-dts para los archivos de declaración.

Una salida habitual para una biblioteca en dos formatos incluye dist/esm/index.js y dist/esm/index.d.ts para consumidores de ESM, y dist/cjs/index.js y dist/cjs/index.cjs para consumidores de CJS. El campo exports de package.json asigna estas rutas a los entornos correspondientes. Los archivos de declaración de TypeScript se encuentran junto a sus archivos JS correspondientes.

Las bibliotecas grandes se benefician de varios puntos de entrada, para que los consumidores solo importen lo que necesitan. Por ejemplo: entry: ['src/index.ts', 'src/utils.ts', 'src/hooks.ts']. Cada punto de entrada obtiene sus propios archivos de salida. El campo exports de package.json asigna cada ruta pública a su salida: './utils' → './dist/utils.js'.

Añada el comando de compilación a los scripts de package.json: "build": "tsup". tsup lee su configuración desde tsup.config.ts en la raíz. El script prepublish debe ejecutar la compilación: "prepublishOnly": "npm run build" garantiza que el paquete siempre se compile antes de publicarlo en npm.

tsup (basado en esbuild) proporciona un empaquetado rápido y sin configuración, con format: ['esm', 'cjs'] y dts: true. Rollup ofrece un control más detallado del tree-shaking mediante @rollup/plugin-typescript. La regla fundamental es marcar siempre react, react-dom y todas las peer dependencies como externas para evitar incluirlas en el bundle. Genere la salida en dist/esm/ y dist/cjs/, con archivos de declaración de TypeScript correspondientes. Los múltiples puntos de entrada permiten un tree-shaking más granular para los consumidores.