manualChunks y chunking avanzado

El algoritmo automático de chunking es bueno, pero no conoce tu producto: no sabe que tu framework y tu librería de UI conviene agruparlos, ni que ese paquete gigante merece su propio chunk. manualChunks es la vía para imponer tu criterio sobre el del bundler, mapeando módulos a chunks con nombre. Es poder de precisión —y, como todo poder de precisión sobre un algoritmo que ya optimizaba solo, la forma más directa de romper lo que funcionaba.

Las dos formas de manualChunks

manualChunks vive en output de las opciones de Rollup, que Vite expone bajo build.rollupOptions. Su forma más simple es un objeto: mapeas un nombre de chunk a la lista de módulos que quieres dentro. Es declarativo y legible, ideal para agrupar dependencias concretas.

// vite.config.ts — forma objeto: nombre de chunk -> modulos
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          "vendor-react": ["react", "react-dom"],
          "vendor-charts": ["d3", "visx"],
        },
      },
    },
  },
});

La forma función es más potente: recibe el id —la ruta absoluta— de cada módulo y devuelve el nombre del chunk donde debe ir, o nada para dejar que el algoritmo automático decida. Con ella expresas reglas dinámicas sobre rutas enteras, imposibles de enumerar a mano.

// forma funcion: una regla que clasifica cada modulo por su id
manualChunks(id) {
  if (id.includes("node_modules")) {
    if (id.includes("react")) return "vendor-react";
    return "vendor";
  }
  if (id.includes("/src/rutas/admin/")) return "ruta-admin";
}

Estrategias de agrupación

La estrategia por tamaño es la más sutil. Una dependencia muy grande merece su propio chunk porque, si cambia, no querrás invalidar nada más con ella; y a la inversa, una constelación de módulos diminutos conviene fundirlos, porque cada chunk tiene un coste fijo de petición que en exceso no compensa. manualChunks te deja implementar ambas políticas donde el automático no llega.

Cuándo tocar esto de verdad es la pregunta clave. La respuesta honesta en 2026: pocas veces. El automático agrupa por alcanzabilidad y acierta en la gran mayoría de los casos; las intervenciones que rinden son las que codifican conocimiento del producto que el bundler no puede deducir del grafo —que dos librerías se versionan al unísono, que una sección es rara y pesada, que un paquete enorme conviene aislar para proteger la caché del resto—. Si tu única justificación para una regla manual es “quería más chunks”, el automático probablemente ya tenía razón.

Los peligros del control manual

Aquí está la trampa. El algoritmo automático garantizaba dos cosas que tú, al tomar el volante, puedes romper sin darte cuenta: que no haya duplicación y que el orden de carga sea correcto.

El segundo riesgo es la duplicación reintroducida: si mandas a mano un módulo compartido a un chunk concreto, puede que otro chunk que también lo necesitaba acabe con su propia copia, deshaciendo justo la optimización que el automático te daba gratis. Y el tercero son los ciclos entre chunks: agrupaciones que se importan mutuamente y que el bundler tiene que resolver con cargas encadenadas, empeorando la cascada que veremos en el próximo nivel.

flowchart TD
subgraph Bien
  A1[entry] --> V1[vendor estable]
  A1 --> C1[compartido]
end
subgraph Mal
  A2[entry] --> X[grupo manual]
  X --> Y[otro grupo manual]
  Y --> X
end
style V1 fill:#a6e3a1,color:#11111b
style X fill:#f38ba8,color:#11111b
style Y fill:#f38ba8,color:#11111b

Rolldown y advancedChunks en 2026

Con Rolldown como motor de Vite 8, la API de chunking manual evoluciona. Rolldown ofrece advancedChunks, un sistema más expresivo que el manualChunks clásico: en lugar de un mapeo plano, defines grupos con condiciones —patrones sobre el id, umbrales de tamaño mínimo y máximo, número mínimo de módulos que comparten un chunk—. Es la respuesta a los casos donde la forma función se volvía un enredo de condicionales.

// Rolldown: advancedChunks con grupos y umbrales
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        advancedChunks: {
          groups: [
            { name: "vendor", test: /node_modules/, minSize: 30000 },
            { name: "admin", test: /\/src\/rutas\/admin\// },
          ],
        },
      },
    },
  },
});

manualChunks sigue soportado por compatibilidad, pero la dirección de 2026 es declarar políticas con umbrales en vez de listas fijas: dile al bundler qué tamaño mínimo justifica un chunk propio y deja que él decida los detalles. Es control sin microgestión, el punto medio entre confiar del todo en el automático y reescribirlo a mano.

Sea cual sea la forma que uses, la regla de oro es verificar en el build de producción, no en desarrollo. En dev, Vite sirve módulos sin aplicar tu estrategia de chunks, así que el efecto de manualChunks o advancedChunks solo se manifiesta tras construir y previsualizar. Muchas configuraciones que parecían correctas resultan inertes —o contraproducentes— cuando por fin se miran en el artefacto real.

Un síntoma fiable de que te has pasado con manualChunks: avisos del bundler sobre chunks vacíos, o un aumento del número de peticiones sin mejora alguna del tiempo de arranque. Cuando aparezcan, la reacción correcta casi nunca es añadir más reglas para parchear el efecto, sino quitar reglas y devolverle el problema al automático, que rara vez producía esos síntomas por su cuenta. La configuración de chunking es de las pocas partes de un build donde menos código suele significar mejor resultado.