Output formats: esm, cjs, iife y umd

El tree shaking y el scope hoisting deciden qué código entra en el bundle; los output formats deciden en qué idioma sale. Rollup construye una vez el grafo y luego lo emite en la forma que pidas: un módulo de ES para bundlers, un módulo de CommonJS para Node, una función autoejecutable para un <script> suelto, o un envoltorio universal que se adapta a lo que encuentre. Elegir bien el formato no es un detalle de configuración: es responder con precisión a la pregunta de quién va a consumir tu código y bajo qué sistema de módulos.

El eje output.format

Toda la elección se concentra en un campo: output.format. Sus valores canónicos son es —con los alias esm y module—, cjs —alias commonjs—, iife, umd, y los heredados amd para RequireJS y system para SystemJS. El grafo es el mismo en todos; lo que cambia es el envoltorio con que Rollup lo entrega y el sistema de carga que ese envoltorio asume del otro lado.

Como output admite un array, un solo build puede emitir varios formatos a la vez. Es el patrón habitual de una librería que quiere servir a consumidores dispares sin reconstruir el grafo tres veces:

// rollup.config.js
export default {
  input: 'src/index.js',
  external: ['react'],
  output: [
    { file: 'dist/index.mjs', format: 'es' },
    { file: 'dist/index.cjs', format: 'cjs' },
    {
      file: 'dist/index.umd.js',
      format: 'umd',
      name: 'MiLib',
      globals: { react: 'React' },
    },
  ],
};

esm y cjs: para sistemas de módulos

El formato esm es el destino por defecto de una librería moderna. Emite import y export tal cual, de modo que el consumidor —otro bundler, o Node con ESM nativo— pueda a su vez analizarlo y hacer tree shaking de lo que no use. Es el único formato que preserva la estructura estática del grafo aguas abajo: al reexportar ESM, no cierras ninguna puerta.

El formato cjs traduce ese mismo grafo a require y module.exports. Su razón de ser es la compatibilidad: Node en su modo clásico, herramientas de test antiguas, y cualquier consumidor que aún no cargue ESM. El coste es que CommonJS no es analizable estáticamente, así que quien importe tu cjs recibe el paquete entero y pierde la capacidad de podarlo. Emites cjs por alcance, no por calidad de salida.

La decisión de qué formato emitir se reduce a quién consume el código y bajo qué sistema de módulos:

• esm: para otro bundler o Node con ESM nativo. El destino por defecto de una librería moderna.
• cjs: para Node clásico o toolchains con require. Se añade por compatibilidad, no por calidad.
• iife: para un <script> suelto que expone un global. El drop-in de navegador sin dependencias.
• umd: para una librería que debe correr en cualquier entorno sin saber cómo la van a cargar.

iife y umd: para el navegador directo

Los dos formatos restantes existen para un mundo sin bundler: cargar un archivo con <script> y usarlo de inmediato. El formato iife envuelve todo en una función que se ejecuta al vuelo —una immediately-invoked function expression— y expone un único global con el nombre que le des en output.name. Es el drop-in clásico: un <script src> y tu librería aparece como window.MiLib, sin ningún sistema de módulos de por medio.

El formato umd —universal module definition— va un paso más allá: al arrancar, detecta el entorno y se adapta. Si hay un cargador AMD, se registra como AMD; si hay CommonJS, se exporta como module.exports; si no hay ninguno, cae en el global como iife. Es el formato universal de las librerías que debían funcionar en cualquier página sin saber de antemano cómo se iban a cargar. Por eso durante años los CDN servían umd por defecto.

Ambos formatos comparten dos exigencias que esm y cjs no tienen. La primera es output.name: como exponen un global, necesitan saber cómo llamarlo. La segunda es output.globals: si tu código depende de algo externo —React, por ejemplo—, en el navegador ese externo también vive como global, y Rollup necesita el mapa que traduce el especificador react al nombre React de window.

// output para un umd que asume React ya cargado en la pagina
{
  format: 'umd',
  name: 'MiLib',
  globals: { react: 'React' },
}

Quedan dos formatos heredados que rara vez elegirás hoy, pero conviene reconocer. amd es el formato de RequireJS, pensado para la carga asíncrona en navegadores anteriores a los módulos nativos; system es el de SystemJS, un cargador dinámico que soportaba ESM y su semántica de live bindings antes de que los navegadores lo hicieran de serie. Ambos pertenecen a una era previa a <script type="module">: emitirlos solo tiene sentido si mantienes un entorno que aún los exige.

flowchart TD
Q[para quien empaquetas] --> L[libreria publicada en npm]
Q --> C[script suelto en el navegador]
Q --> A[aplicacion con bundler]
L --> ES[formato es y opcional cjs]
C --> II[formato iife o umd con name]
A --> CH[formato es troceado en chunks]

El campo exports es quien conecta cada condición de carga con el archivo del formato correcto, y es la pieza que hace usable un paquete dual:

{
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}