Cómo la usan los frameworks: SSR y edge de forma uniforme

Una API de plataforma se mide por lo que deja de existir río abajo. Antes de la Environment API, cada meta-framework cargaba con su propio runner de servidor, su propio puente de HMR y su propia forma de fingir el edge. Con ella, todos convergen en un mismo primitivo: un entorno por runtime de despliegue, contribuido por un adaptador. Este nivel mira cómo Astro, SolidStart, TanStack Start y el plugin de Cloudflare usan la API, y por qué el caso de workerd es el que mejor muestra la ganancia: por primera vez, el dev del edge corre en el edge.

El patrón común: un entorno por adaptador

Todos los meta-frameworks resuelven la misma ecuación: tomar tu código y hacerlo correr en un runtime de despliegue —Node, Cloudflare, Vercel, Deno—. Antes, cada uno lo hacía a su manera, reimplementando por dentro un trozo del pipeline de Vite: un runner tipo vite-node, un empaquetado manual del servidor, un juego de polyfills. La Environment API les ofrece un lugar canónico donde encajar ese trabajo: el adaptador aporta un environment.

Un adaptador de despliegue, en el mundo nuevo, es esencialmente una fábrica de entornos. Declara un entorno con las condiciones de resolución de su runtime, provee un createEnvironment que sabe instanciar ese runtime en dev y coloca un ModuleRunner dentro de él conectado por un transport. A partir de ahí, Vite hace el resto: transforma una vez por entorno, el runtime ejecuta, y el HMR fluye por el canal del entorno. El framework deja de mantener su runner.

// Esbozo de un adaptador: aporta un entorno via config, no un runner propio
function adaptadorEdge(): Plugin {
  return {
    name: 'adaptador-edge',
    config() {
      return {
        environments: {
          edge: {
            consumer: 'server',
            resolve: { conditions: ['worker', 'browser', 'import'] },
            dev: {
              // instancia el runtime real y coloca dentro un ModuleRunner
              createEnvironment(name, config) {
                return crearDevEnvironmentEnElRuntime(name, config)
              },
            },
          },
        },
      }
    },
  }
}

Lee ese esbozo como la esencia de un adaptador moderno: no trae un runner ni un bundler propios, solo declara un entorno y provee la factoría que sabe instanciar su runtime. Todo lo demás —transformar, resolver, cachear, propagar el HMR— lo pone Vite. El adaptador aporta conocimiento del destino; la plataforma aporta la maquinaria.

Ese es el giro que abarata tanto la adopción de la API para un framework: la superficie que debe implementar se reduce a lo irreducible. Antes, soportar un runtime nuevo era escribir medio Vite; ahora es escribir una factoría y unas condiciones. La barrera de entrada para modelar un destino cae de un proyecto a una función.

flowchart LR
ad[Adaptador de despliegue] --> ef[createEnvironment]
ef --> env[Environment del runtime]
env --> mr[ModuleRunner dentro del runtime]
env --> cond[condiciones y transforms del destino]
style ad fill:#cba6f7,color:#11111b
style env fill:#89b4fa,color:#11111b
style mr fill:#a6e3a1,color:#11111b

Conviene subrayar el reparto de responsabilidades que esto instaura. Vite se queda con lo genérico —transformar, resolver, cachear, propagar el HMR— y el adaptador se queda solo con lo específico de su runtime: cómo se arranca, qué globales inyecta, dónde vive su ModuleRunner. Esa línea limpia entre lo común y lo particular es la razón de que la misma API sirva por igual a un adaptador de Node trivial y a uno de workerd que orquesta Miniflare.

Cloudflare y workerd: dev igual que producción

El caso más nítido es el plugin oficial de Cloudflare para Vite. Su objetivo es que tu Worker corra, en desarrollo, dentro del mismo runtime que en producción: workerd, a través de Miniflare. Para lograrlo declara un entorno cuyo ModuleRunner vive dentro del Worker; cuando llega una petición, Vite transforma el módulo con las condiciones de workerd y el runner lo ejecuta en el runtime real, no en un simulacro de Node.

La consecuencia es enorme y concreta: los globales, la resolución de módulos y las restricciones que ves en dev son los de workerd. Si usas un binding de KV, R2 o D1, está disponible en desarrollo con su semántica auténtica. El bug de “funcionaba en local y reventó al desplegar” —el síntoma que definía la era de los dos grafos— desaparece porque local y despliegue son el mismo runtime.

// vite.config.ts con el plugin de Cloudflare
import { defineConfig } from 'vite'
import { cloudflare } from '@cloudflare/vite-plugin'

export default defineConfig({
  plugins: [cloudflare()],
  // el plugin declara un entorno workerd y ejecuta tu Worker
  // dentro de Miniflare, con HMR, en el runtime real del edge
})

Astro, SolidStart y el caso de los RSC

El mismo primitivo sirve a frameworks de propósito distinto. Astro mueve su integración con Vite hacia los entornos para que sus adaptadores —Node, Cloudflare, Vercel— se expresen como environments y sus islas de servidor y el soporte de componentes de servidor descansen sobre varios grafos. SolidStart y TanStack Start convergen en lo mismo: en lugar de una capa propia que orquesta runtimes —el papel que antes jugaban proyectos como Vinxi o Nitro—, se apoyan en los entornos de Vite para modelar cliente y servidor de forma uniforme.

La lista sigue: React Router, tras absorber Remix, apunta al mismo primitivo para su renderizado de servidor; y proyectos como el SDK de Redwood para Cloudflare nacen ya asumiendo los entornos como base para servir RSC sobre workerd. Lo revelador no es qué framework concreto lo adopta antes, sino que todos convergen a la misma pieza en lugar de multiplicar soluciones incompatibles. Cuando competidores que no se coordinan eligen el mismo cimiento, suele ser porque el cimiento captura una verdad del dominio que ninguno puede permitirse ignorar.

Los React Server Components son el banco de pruebas más exigente, y por eso el más revelador. Una app con RSC necesita tres grafos coexistiendo: el entorno de servidor que ejecuta los componentes de servidor, el de SSR que convierte su salida en HTML y el de cliente que hidrata en el navegador. Cada uno resuelve los paquetes con condiciones distintas —la directiva de cliente marca la frontera— y cada uno tiene su transform. Modelar eso con dos grafos cableados era imposible sin parches; con la Environment API es, literalmente, declarar tres entornos. Que el patrón más complejo del frontend actual se exprese como una lista de entornos es la mejor prueba de que la abstracción está bien puesta.

El dividendo compartido: plugins portables

Hay un beneficio que solo se ve cuando miras el ecosistema entero en lugar de un framework aislado. Como todos hablan el mismo primitivo —entornos con nombre, this.environment en los hooks, applyToEnvironment para acotar—, un plugin escrito contra la Environment API funciona igual bajo Astro, bajo SolidStart o bajo el plugin de Cloudflare. Antes, un plugin que quisiera comportarse distinto en servidor tenía que adivinar el contexto con heurísticas frágiles; ahora lo pregunta a la API, y la respuesta es la misma sea cual sea el framework que la envuelve.

// El mismo plugin, valido en cualquier framework que use la Environment API
function soloEnEdge(): Plugin {
  return {
    name: 'solo-en-edge',
    applyToEnvironment(env) {
      return env.name === 'workerd'   // no depende del framework, solo del entorno
    },
    transform(code) {
      return this.environment.name === 'workerd' ? adaptarAlEdge(code) : null
    },
  }
}

Esta portabilidad es la que empieza a desfragmentar el ecosistema. La comunidad de plugins deja de bifurcarse por framework y se reorganiza alrededor de los entornos, que es la frontera que de verdad importa. Un autor de plugins mantiene una sola implementación; un usuario la instala sin preguntarse si “es compatible con mi meta-framework”, porque la pregunta correcta pasó a ser otra: “¿qué entornos toca?”.