Config de input y output: entradas, chunks y externals

Toda la configuración de Rollup gira sobre dos polos. input responde por dónde entra el grafo: uno o varios puntos de partida desde los que se teje todo. output responde cómo sale: en qué formato, en cuántos archivos, con qué nombres, y qué queda fuera. Dominar ese par —y las decisiones intermedias de troceado y externalización— es lo que separa un bundle que simplemente funciona de uno que cachea bien, no duplica código y no arrastra dependencias que el consumidor ya tiene.

Las tres formas de input

El campo input acepta tres formas, y cada una expresa una intención distinta. La más simple es una cadena: un único punto de entrada del que cuelga todo el grafo. La segunda es un array de rutas, útil cuando tu librería o tu app tiene varias entradas independientes; Rollup deriva el nombre de cada chunk de su archivo. La tercera, y la más expresiva, es un objeto: las claves se convierten en el nombre de cada entrada, lo que te da control explícito sobre cómo se llamará cada chunk de salida.

// rollup.config.js — entradas nombradas por las claves del objeto
export default {
  input: {
    main: 'src/main.js',
    admin: 'src/admin/index.js',
  },
  output: {
    dir: 'dist',
    format: 'es',
    entryFileNames: '[name]-[hash].js',
    chunkFileNames: 'chunks/[name]-[hash].js',
    assetFileNames: 'assets/[name]-[hash][extname]',
  },
  external: ['react', 'react-dom'],
};

La forma de objeto es la que usarás en cuanto tengas más de una entrada, porque la clave —main, admin— alimenta el placeholder [name] de los nombres de archivo. Con la forma de array pierdes ese control fino sobre los nombres; con la de objeto, cada entrada sale con la etiqueta que tú decides.

output.dir, output.file y los nombres

En el lado de salida, la primera bifurcación es entre output.file y output.dir. Usa output.file —una única ruta— solo cuando el build produce un solo chunk: una entrada, sin imports dinámicos, sin troceado. En cuanto hay varias entradas, un import() dinámico o un manualChunks, la salida son varios archivos y debes usar output.dir, el directorio donde Rollup los deposita. Intentar output.file con varios chunks es un error directo.

Los nombres de esos archivos se controlan con tres patrones y un puñado de placeholders. output.entryFileNames nombra los chunks de entrada, output.chunkFileNames los chunks compartidos o cargados dinámicamente, y output.assetFileNames los recursos como CSS o imágenes. Dentro de cada patrón, [name] es la etiqueta de la entrada o del asset, [hash] es un hash del contenido, y [extname] la extensión original.

Los placeholders forman un vocabulario corto que combinas dentro de cada patrón:

• [name]: la etiqueta de la entrada o del asset, tomada de la clave de input.
• [hash]: un hash del contenido del chunk, la base del caché a largo plazo.
• [format]: el formato de salida, útil cuando un mismo build emite varios a la vez.
• [extname]: la extensión original del asset, con su punto incluido.

El [hash] no es decorativo: es la base del caché a largo plazo. Si el nombre incluye un hash del contenido, cualquier cambio en el archivo produce un nombre nuevo, de modo que puedes servir esos assets con caché inmutable y confiar en que el navegador descargará la versión nueva solo cuando de verdad cambie. Un chunk de vendor que no varía entre despliegues conserva su nombre, y el usuario no vuelve a descargarlo.

manualChunks y external

Por defecto, Rollup decide el troceado solo: junta lo que puede y separa lo que comparten varios puntos de entrada. Cuando quieres imponer tu criterio —típicamente, aislar las dependencias de node_modules en un chunk de vendor estable—, usas manualChunks. Tiene dos formas: un objeto que mapea un nombre de chunk a una lista de módulos, o una función que recibe el id de cada módulo y devuelve el nombre del chunk al que debe ir.

output: {
  dir: 'dist',
  manualChunks(id) {
    if (id.includes('node_modules')) return 'vendor';
  },
}

En el ecosistema de 2026, con Rolldown como motor de Vite 8, manualChunks sigue soportado por compatibilidad, pero convive con un sucesor más expresivo: output.advancedChunks, que define grupos con reglas de test, tamaño mínimo y prioridad, en vez de una sola función. La idea es la misma —controlar dónde caen los módulos—, pero con una gramática que expresa políticas de troceado sin escribir imperativamente cada caso.

// Rolldown y Vite 8: agrupacion declarativa por reglas
output: {
  advancedChunks: {
    groups: [{ name: 'vendor', test: 'node_modules' }],
  },
}

El otro control decisivo es external. Marca módulos que Rollup no debe incluir en el bundle: en lugar de empaquetarlos, los deja como import o require en la salida, confiando en que el consumidor los provea. Para una librería es casi obligatorio externalizar sus peer dependencies —no quieres empaquetar React dentro de tu librería y que el consumidor acabe con dos copias—. Para una app, se externaliza lo que va a estar disponible en el entorno de ejecución, como los módulos nativos de Node bajo el prefijo node:.

// external como lista y como funcion
export default {
  external: ['react', 'react-dom'],
  // o, para excluir todos los builtins de Node:
  // external: (id) => id.startsWith('node:'),
};

flowchart TD
I[input objeto con claves] --> G[grafo de modulos]
G --> S[troceado en chunks]
S --> E[entry chunks segun entryFileNames]
S --> C[chunks compartidos segun chunkFileNames]
S --> A[assets segun assetFileNames]
X[modulos external fuera del grafo] --> S