La API: environments configurables, ModuleRunner y transforms por entorno

Aquí abrimos la caja. La Environment API se sostiene sobre una separación limpia entre dos responsabilidades que Vite 5 mezclaba: transformar código y ejecutarlo. El DevEnvironment transforma —resuelve, aplica plugins, cachea en su grafo— pero no ejecuta. El ModuleRunner ejecuta —evalúa el código transformado en un runtime concreto— pero no transforma. Entre ambos, un transport. Esa frontera es lo que permite que el código de servidor corra donde debe correr, incluso en otro proceso o en otro runtime, y es la pieza que reemplaza para siempre a ssrLoadModule.

El DevEnvironment transforma, no ejecuta

Un DevEnvironment es la mitad del sistema que vive dentro del proceso de Vite. Su trabajo es tomar una URL de módulo, resolverla con las condiciones del entorno, pasarla por los plugins de ese entorno y devolver código transformado, dejándolo cacheado en su EnvironmentModuleGraph. Lo que no hace es evaluarlo: el DevEnvironment no sabe ejecutar tu servidor, solo sabe prepararlo.

const server = await createServer()
const env = server.environments.ssr        // un DevEnvironment
const result = await env.transformRequest('/src/entry-server.ts')
// result.code es codigo listo para evaluar, PERO nadie lo ha ejecutado aun

Esta parcialidad es deliberada. Al no ejecutar, el DevEnvironment no impone dónde se ejecuta: no obliga a Node, no obliga al mismo proceso, no obliga a nada. Deja esa decisión para la otra mitad, y en esa libertad está toda la potencia de la API.

El ModuleRunner ejecuta el código de servidor

El ModuleRunner, importado de vite/module-runner, es la mitad que ejecuta. Vive en el runtime de destino —Node, un Worker, un thread aparte— y pide módulos al DevEnvironment a través de un transport. Cuando le pides importar una URL, el runner la solicita, el entorno la transforma y la devuelve, y un evaluator ejecuta ese código en el runtime donde el runner vive.

import { ModuleRunner, ESModulesEvaluator } from 'vite/module-runner'

const runner = new ModuleRunner(
  {
    transport,               // el canal hacia el DevEnvironment que transforma
  },
  new ESModulesEvaluator(),  // como se evalua el codigo EN ESTE runtime
)

// el runner pide, el entorno transforma, el evaluator ejecuta aqui mismo
const mod = await runner.import('/src/entry-server.ts')
mod.render()

La clave está en que vite/module-runner es un paquete minúsculo y sin dependencias de Node: puede correr dentro de workerd, de Deno o de un Web Worker. El transport es una interfaz de mensajería abstracta —puede ser una llamada de función en el mismo proceso, un MessagePort entre threads o un socket entre procesos—. Esa abstracción es la que despega la ejecución del servidor de Vite: el código se transforma en un sitio y se ejecuta en otro, y entre medias solo viajan mensajes.

flowchart LR
R[ModuleRunner en el runtime destino] -- pide url --> T[transport]
T --> D[DevEnvironment en el proceso de Vite]
D -- transforma con plugins y condiciones --> T
T -- codigo transformado --> R
R -- evaluator ejecuta --> X[modulo vivo en el runtime real]
style R fill:#89b4fa,color:#11111b
style D fill:#cba6f7,color:#11111b
style X fill:#a6e3a1,color:#11111b

Cuando el runtime de destino es el mismo proceso de Node donde corre Vite —el caso más simple—, no necesitas cablear el transport a mano. Vite ofrece un RunnableDevEnvironment: un DevEnvironment que ya trae un ModuleRunner incorporado y conectado, con un método runner.import.

import { createServer, isRunnableDevEnvironment } from 'vite'

const server = await createServer()
const env = server.environments.ssr
if (isRunnableDevEnvironment(env)) {
  const mod = await env.runner.import('/src/entry-server.ts')
  mod.render()   // ejecutado en este mismo proceso Node
}

El transport: la interfaz que lo hace portable

Si el ModuleRunner puede vivir en Node, en workerd o en un thread, es porque no habla directamente con el DevEnvironment, sino con un transport: una interfaz de mensajería mínima que abstrae cómo viajan las peticiones y las respuestas. El runner pide un módulo; el transport lleva esa petición al entorno y trae de vuelta el código transformado. Ni el runner sabe dónde está el entorno, ni el entorno sabe dónde está el runner.

// La forma esencial de un transport: enviar peticiones y recibir respuestas
interface Transport {
  // el runner pide; la implementacion decide COMO cruza la frontera
  fetchModule(id: string, importer?: string): Promise<FetchResult>
  // canal opcional para HMR y mensajes del entorno hacia el runner
  connect?(handlers: TransportHandlers): void
}

Que sea una interfaz y no una implementación concreta es justo lo que la vuelve portable. En el mismo proceso, el transport es una llamada de función directa. Entre threads, se apoya en un MessagePort. Entre procesos, o hacia un runtime remoto, en un socket o en el protocolo que ese runtime exponga. La forma del contrato no cambia; solo cambia el mensajero, y por eso una misma pieza de ejecución sirve para escenarios que antes exigían máquinas distintas.

Aquí se cierra la idea de la lección. El DevEnvironment transforma sin saber quién ejecutará; el ModuleRunner ejecuta sin saber quién transformó; el transport los une sin acoplarlos. Tres piezas con fronteras nítidas, cada una ignorante de las otras dos salvo por su contrato, que es la definición misma de un sistema desacoplado y la razón de que la API escale a runtimes que sus autores ni siquiera anticiparon.

Transforms y hooks por entorno

La tercera pieza es que los plugins ahora saben en qué entorno operan. Dentro de cualquier hook, this.environment es la instancia del entorno actual, con su name y su config. Eso convierte cada plugin en algo consciente del destino sin duplicar plugins.

function miPlugin(): Plugin {
  return {
    name: 'mi-plugin',
    // se aplica solo a los entornos que quieras
    applyToEnvironment(env) {
      return env.name === 'workerd'
    },
    transform(code, id) {
      // this.environment dice DONDE se esta transformando
      if (this.environment.name === 'ssr') {
        return inyectarSoloEnServidor(code)
      }
      return null
    },
    // HMR por entorno: sustituye al viejo handleHotUpdate global
    hotUpdate(ctx) {
      // ctx.environment identifica el entorno; ctx.modules son SUS modulos
      if (ctx.environment.name === 'client') {
        // invalidar solo el grafo del cliente
      }
    },
  }
}

Tres hooks marcan el cambio de era. applyToEnvironment decide si un plugin se activa en un entorno dado, permitiendo pipelines distintos por destino. transform —y resolveId, y load— reciben this.environment, así que un mismo plugin puede comportarse distinto en cliente y en servidor sin bifurcarse en dos. Y hotUpdate, que reemplaza al antiguo handleHotUpdate, opera por entorno: recibe los módulos del grafo de ese entorno concreto, de modo que un cambio en un archivo invalida solo los grafos que de verdad lo contienen.

La consecuencia práctica es que desaparece un patrón feo y frágil: el de consultar variables globales o inspeccionar el id con expresiones regulares para adivinar “¿esto es servidor o cliente?”. Esa pregunta ahora tiene una respuesta autoritativa y local, this.environment, disponible en el sitio exacto donde la necesitas. Un plugin bien escrito contra la Environment API no deduce su contexto: lo lee, y esa diferencia entre adivinar y saber es lo que vuelve robusto el código de plugins que antes vivía de heurísticas.