El sistema de plugins de Rollup: el estándar heredado

Rollup casi no hace nada por sí solo: su núcleo construye un grafo y emite bytes, y todo lo demás —compilar TypeScript, resolver alias, inyectar datos, cargar formatos raros— lo hacen plugins colgados de una serie de hooks bien definidos. Ese sistema de hooks resultó tan acertado que se volvió el estándar de facto del empaquetado: Vite lo adoptó como superconjunto y Rolldown lo reimplementa en Rust sin cambiar el contrato. Entender su arquitectura —dos fases, tres tipos de hook y un contexto compartido— es entender el lenguaje común de toda una generación de herramientas.

Un plugin y sus dos fases

Un plugin de Rollup es un objeto plano: lo único obligatorio es name, y el resto son funciones-hook que el bundler invoca en momentos concretos. Por convención se envuelve en una factoría que acepta opciones y devuelve el plugin, para poder parametrizarlo al usarlo. No hay clases, ni ciclo de vida propio, ni magia: solo un contrato de funciones con nombres reservados.

export function miPlugin(opciones = {}) {
  return {
    name: 'mi-plugin',
    buildStart() {
      this.info('empieza la fase de build');
    },
    generateBundle(output, bundle) {
      this.info('empieza la fase de output');
    },
  };
}

La clave arquitectónica es que esos hooks se reparten en dos fases nítidas. Primero corre la fase de build: Rollup parte de los puntos de entrada, resuelve y carga cada módulo, lo transforma, parsea su AST y descubre sus imports, y así teje el grafo completo. Solo cuando el grafo está cerrado empieza la fase de output: Rollup trocea ese grafo en chunks, les da forma según el output.format, y escribe los archivos. Un mismo build puede tener una sola fase de build y varias de output —una por cada entrada del array output—.

Hooks de build y hooks de output

Los hooks de build son los que has visto ya en el nivel anterior aplicados a Vite: options normaliza la configuración, buildStart marca el arranque, resolveId traduce un especificador a un id, load entrega el fuente, transform lo reescribe, moduleParsed se dispara cuando un módulo ya tiene su AST, y buildEnd cierra la fase. La recursión sobre los imports descubiertos ocurre entre transform y moduleParsed, y de repetirla emerge el grafo.

Los hooks de output pertenecen a un mundo distinto, el de dar forma al artefacto. outputOptions ajusta las opciones de salida, renderStart abre la generación, renderChunk reescribe cada chunk ya troceado —el momento de inyectar un banner o de transformar el código final—, generateBundle recibe el bundle completo en memoria justo antes de escribirlo —ideal para emitir un manifest o un archivo extra—, y writeBundle corre después de que los archivos toquen el disco. closeBundle cierra todo al final.

Esa separación no es burocrática: delimita qué puedes hacer y cuándo. En build tienes acceso al grafo de módulos pero aún no a los chunks; en output tienes los chunks pero el grafo ya está congelado. Un plugin que intenta emitir un chunk nuevo lo hace en build con this.emitFile; uno que quiere leer el resultado final lo hace en generateBundle. Confundir la fase es el error de diseño más común al escribir un plugin.

El orden dentro de cada fase es fijo, y memorizar la secuencia ayuda a saber dónde engancharse:

• Build: options, buildStart, resolveId, load, transform, moduleParsed y buildEnd.
• Output: renderStart, renderChunk, generateBundle, writeBundle y closeBundle.

flowchart LR
subgraph Fase_de_build
  O1[options] --> BS[buildStart]
  BS --> RI[resolveId]
  RI --> LD[load]
  LD --> TR[transform]
  TR --> MP[moduleParsed]
  MP --> BE[buildEnd]
end
subgraph Fase_de_output
  RS[renderStart] --> RC[renderChunk]
  RC --> GB[generateBundle]
  GB --> WB[writeBundle]
end
BE --> RS

Tipos de hook y el contexto this

Con decenas de plugins activos, importa tanto qué hace cada hook como cómo se combinan varios sobre el mismo punto. Rollup clasifica los hooks en tres tipos según esa combinación. Los de primero que gana —resolveId, load— modelan decisiones únicas: Rollup recorre los plugins y se queda con el primer resultado no nulo, porque la identidad y el contenido de un módulo son una sola cosa. Los secuenciales —transform, renderChunk— modelan una tubería: corren todos en orden y la salida de uno alimenta al siguiente. Los paralelos —buildStart, buildEnd, writeBundle— solo reaccionan a un momento, no compiten ni encadenan, así que Rollup los lanza a la vez.

Saber a qué tipo pertenece un hook te dice de antemano tu papel: si compites por resolver, si colaboras en una cadena, o si solo reaccionas. Y para afinar el orden dentro de un tipo, cualquier hook admite su forma de objeto con order —pre, post o nulo— y handler, más quirúrgica que mover el plugin entero.

El contraste se ve en dos hooks: uno decide, el otro encadena.

// first-wins: el primer resultado no nulo cierra la pregunta
resolveId(source) {
  return source === 'virtual:datos' ? '\0virtual:datos' : null;
}

// secuencial: corren todos y la salida de uno alimenta al siguiente
transform(code, id) {
  return id.endsWith('.especial') ? { code: reescribir(code), map: null } : null;
}

Dentro de cualquier hook, this es la ventana del plugin al bundler. No es una función suelta que recibe datos: puede pedirle cosas al motor mientras corre.

• this.resolve y this.load invocan la resolución y la carga de otro módulo desde dentro del tuyo.
• this.emitFile añade un chunk o un asset a la salida, y this.getFileName recupera su ruta final.
• this.getModuleInfo y this.parse inspeccionan el grafo y producen un AST sin reimplementar un parser.
• this.addWatchFile vigila un archivo externo, y this.error y this.warn emiten diagnósticos ubicados.