El concepto de environment: módulos aislados por destino

Si la lección anterior fue el diagnóstico, esta es la definición. Un environment no es un modo ni un flag: es una configuración de módulos aislada, atada a un runtime de destino concreto. Tiene un nombre, unas condiciones de resolución, un grafo de módulos propio y un pipeline de transforms propio. El cliente es un environment; el SSR de Node es otro; workerd es un tercero. Entender qué contiene un environment y qué lo separa de sus vecinos es la llave conceptual de todo el nivel.

De un flag a un objeto de primera clase

En Vite 5 el “entorno” era un adjetivo del transform: pasabas ssr: true y la misma tubería se comportaba distinto. En la Environment API el entorno pasa a ser un sustantivo: un objeto con identidad, estado y ciclo de vida. En lugar de preguntar “¿estoy transformando para SSR?”, ahora preguntas “¿en qué entorno estoy?”, y la respuesta es una instancia con nombre —client, ssr, workerd— que lleva consigo toda su configuración.

Ese cambio de adjetivo a sustantivo es lo que permite pluralizar. Un adjetivo binario solo distingue dos casos; un objeto con nombre admite tantos como declares. Por eso la primera consecuencia de la API es que los entornos dejan de estar cableados en el server y pasan a vivir en un mapa, server.environments, indexado por nombre.

// De preguntar por un flag a preguntar por una instancia con nombre
const server = await createServer()
server.environments.client   // DevEnvironment del navegador
server.environments.ssr      // DevEnvironment de Node
server.environments.workerd  // DevEnvironment del edge, si lo declaraste

Anatomía de un environment

Un environment agrupa cuatro cosas que antes andaban dispersas o cableadas. Verlas por separado aclara qué lo convierte en un entorno y no en otro.

El aislamiento es la propiedad central. Que cada entorno tenga su propio grafo significa que un módulo transformado para el cliente y el mismo módulo transformado para workerd son entradas distintas, con contenido distinto, cacheadas por separado. No hay filtración entre destinos: precisamente el fallo que hacía que dev no coincidiera con producción cuando todo compartía un único grafo de SSR.

// Cada entorno trae su propio grafo y su propio transform
const ssr = server.environments.ssr
ssr.moduleGraph                            // EnvironmentModuleGraph, solo suyo
await ssr.transformRequest('/src/app.ts')  // con las condiciones y plugins de ssr
ssr.hot                                     // su canal de HMR, independiente

Declarar entornos: client, ssr y más allá

Por defecto Vite crea dos entornos, client y ssr, para no romper nada. Pero ahora son valores por defecto de una lista abierta, no un binario cerrado. Declarar un tercero es añadir una clave al objeto environments de la config.

// vite.config.ts
export default defineConfig({
  environments: {
    client: {},                                   // el navegador, por defecto
    ssr: {
      consumer: 'server',
      resolve: { conditions: ['node', 'import'] },
    },
    workerd: {
      consumer: 'server',
      resolve: { conditions: ['workerd', 'worker', 'browser', 'import'] },
    },
  },
})

Cada entrada describe un runtime. El campo consumer dice si el entorno lo consume un cliente (navegador) o un servidor, lo que cambia decisiones por defecto como si los assets se sirven o se empaquetan. Las conditions fijan cómo resuelve los paquetes: fíjate en que workerd pide primero su propia condición y luego cae a worker y browser, porque el edge se parece más al navegador que a Node. Con esas tres claves ya tienes tres grafos aislados, tres pipelines y tres formas de resolver, todos derivados de una config declarativa.

flowchart TB
cfg[environments en vite config] --> cl[client]
cfg --> sr[ssr]
cfg --> wk[workerd]
cl --> clg[grafo propio y condiciones browser]
sr --> srg[grafo propio y condiciones node]
wk --> wkg[grafo propio y condiciones workerd worker browser]
style cfg fill:#cba6f7,color:#11111b
style clg fill:#89b4fa,color:#11111b
style srg fill:#a6e3a1,color:#11111b
style wkg fill:#fab387,color:#11111b

Cómo nace un entorno: herencia y factoría

Un entorno no se configura desde cero: hereda la config de nivel superior como base y luego la especializa. Lo que escribes en la raíz de defineConfig —resolve, optimizeDeps, define— actúa como valor por defecto para todos los entornos, y cada entrada de environments solo necesita declarar en qué se desvía. Esa herencia evita repetir lo común y deja el bloque de cada entorno centrado en lo que de verdad lo distingue.

// La raiz es el valor por defecto; cada entorno solo declara su desviacion
export default defineConfig({
  resolve: { alias: { '@': '/src' } },   // comun a todos los entornos
  environments: {
    ssr: {
      resolve: { conditions: ['node', 'import'] },   // solo lo propio de ssr
    },
    workerd: {
      resolve: { conditions: ['workerd', 'worker', 'browser'] },
    },
  },
})

Conviene conocer la semántica de la mezcla, porque no siempre es intuitiva: los escalares del entorno sobrescriben a los de la raíz, pero listas como conditions no se fusionan silenciosamente, sino que el entorno fija las suyas. Saber si un campo hereda, sustituye o acumula es lo que evita sorpresas cuando un paquete resuelve a un fichero que no esperabas: casi siempre la causa está en qué condiciones ganó el entorno, no en la raíz.

La otra pieza es la factoría. Cada entorno declara cómo se instancia mediante un createEnvironment, distinto para dev y para build. Esa factoría decide de qué tipo concreto es la instancia: un RunnableDevEnvironment para lo que corre en el mismo proceso, o una implementación a medida —como la que provee el plugin de Cloudflare— para lo que corre dentro de workerd. Vite fija la forma común del entorno; la factoría rellena el “cómo” específico de cada runtime.

flowchart LR
base[config raiz como base] --> env[cada environment hereda y especializa]
env --> devf[createEnvironment en dev]
env --> bldf[createEnvironment en build]
style base fill:#cba6f7,color:#11111b
style env fill:#89b4fa,color:#11111b
style devf fill:#a6e3a1,color:#11111b
style bldf fill:#fab387,color:#11111b

Junta las dos ideas y tienes el retrato completo de un entorno: una config que hereda de la raíz y se especializa, y una factoría que sabe darle cuerpo en cada fase. Con eso, “declarar un entorno” deja de ser magia y pasa a ser un contrato claro —qué resuelve, qué transforma, cómo se instancia— que cualquier adaptador puede cumplir sin tocar el núcleo de Vite.