El modelo de plugins de Vite

Vite no es un monolito con funciones cableadas por dentro; es un núcleo diminuto y un sistema de plugins que hace casi todo el trabajo real. Y ese sistema no lo inventó Vite: reutiliza la interfaz de plugins de Rollup y la amplía con hooks propios para el dev server, el HTML de entrada y el HMR. Un plugin de Vite es, literalmente, un objeto con un name y un puñado de funciones-hook. Entender esa arquitectura —qué hereda de Rollup, qué añade encima, y en qué orden corre todo— es la llave que abre el nivel entero.

Un plugin es un objeto con hooks

La unidad mínima de extensión en Vite no es una clase ni un framework de plugins con ciclo de vida propio: es un objeto plano. Lo único obligatorio es name, una cadena que identifica al plugin en los mensajes de error y en las trazas. Todo lo demás son hooks, funciones que Vite invoca en momentos concretos del build y del servidor. Por convención se envuelve ese objeto en una función factoría que acepta opciones y devuelve el plugin, para poder parametrizarlo al configurarlo.

// mi-plugin.ts
import type { Plugin } from 'vite'

export function miPlugin(opciones = {}): Plugin {
  return {
    name: 'mi-plugin',
    enforce: 'pre',
    buildStart() {
      this.warn('el build acaba de empezar')
    },
    transform(code, id) {
      if (!id.endsWith('.especial')) return null
      return { code: reescribir(code), map: null }
    },
  }
}

La clave conceptual: un plugin de Vite es un superconjunto de un plugin de Rollup. Todos los hooks de build de Rollup —options, buildStart, resolveId, load, transform, buildEnd— y los de generación de salida —renderStart, renderChunk, generateBundle, writeBundle— funcionan igual dentro de un plugin de Vite. Encima de esa base, Vite inyecta hooks que Rollup no tiene porque no le hacen falta a un bundler puro: config, configResolved, configureServer, transformIndexHtml y handleHotUpdate. Los primeros los estudiaremos en la lección 2; los segundos, en la 3.

En Vite 8, el bundler por debajo ya no es Rollup sino Rolldown, escrito en Rust dentro del proyecto Oxc. Esto no rompe nada: Rolldown implementa deliberadamente la misma interfaz de plugins de Rollup, así que la práctica totalidad del ecosistema sigue funcionando sin cambios. Lo que sí aparece es un mecanismo nuevo, los hook filters: puedes declarar de forma estática qué módulos le interesan a un hook, y Rolldown se ahorra cruzar la frontera entre Rust y JavaScript para los módulos que no encajan. Es una optimización que solo tiene sentido cuando el núcleo es nativo.

El orden lo es todo: enforce

Con decenas de plugins activos, la pregunta crítica deja de ser qué hace cada uno y pasa a ser en qué orden corren. Vite resuelve esto con el campo enforce, que admite tres valores: 'pre', nada (normal) y 'post'. No es una prioridad numérica libre, sino tres cubos ordenados, y dentro de cada cubo los plugins respetan el orden del array de configuración.

flowchart TD
A[alias] --> B[plugins con enforce pre]
B --> C[plugins nucleo de Vite]
C --> D[plugins normales sin enforce]
D --> E[plugins de build de Vite]
E --> F[plugins con enforce post]
F --> G[plugins post build de Vite]

La tubería completa intercala tus plugins con los del propio Vite. Primero se resuelven los alias; luego corren tus plugins pre, antes que el núcleo de Vite, justo donde debe ir un plugin de framework que necesita transformar el fuente antes de que Vite lo toque. Después van los plugins del núcleo, luego tus plugins normales, luego los de build de Vite, y al final tus plugins post, cuya salida ya no verá ningún plugin normal. Los plugins post build de Vite —minificación, manifest, informe de tamaños— cierran la marcha.

El enforce de plugin es un instrumento grueso; a veces necesitas que solo un hook concreto se adelante o se atrase. Para eso, cualquier hook puede escribirse en su forma de objeto, con order y handler separados. Es más quirúrgico que mover el plugin entero:

export function miPlugin(): Plugin {
  return {
    name: 'mi-plugin',
    transform: {
      order: 'pre',
      handler(code, id) {
        return null
      },
    },
  }
}

apply y la doble naturaleza serve o build

Vite vive dos vidas: un dev server que sirve ESM sin empaquetar y un build de producción que sí empaqueta. Un plugin puede tener sentido en una y no en la otra. El campo apply acota su alcance: acepta 'serve', 'build' o una función que decide según la configuración y el entorno resueltos.

export function soloEnBuild(): Plugin {
  return {
    name: 'solo-en-build',
    apply: 'build',
  }
}

export function condicional(): Plugin {
  return {
    name: 'condicional',
    apply(config, { command }) {
      return command === 'build' && !config.build?.ssr
    },
  }
}

Un plugin sin apply corre en ambas fases, que es lo correcto para la mayoría: los hooks de Rollup como transform se ejecutan tanto en el dev server —de forma perezosa, módulo a módulo— como en el build. La razón para acotar suele ser el coste o la seguridad: una transformación cara que solo aporta en producción se marca apply: 'build'; un middleware de depuración, apply: 'serve'. En Vite 8, además, cada hook recibe el entorno activo por this.environment, de modo que un mismo plugin puede comportarse distinto en el entorno de cliente y en el de servidor sin duplicarse.