Adaptadores full-stack: Astro, React Router y SvelteKit

Hono es perfecto cuando quieres un router y poco más, pero a menudo llegas al edge con un framework full-stack ya en la mano: Astro para contenido, React Router para aplicaciones o SvelteKit para lo que sea. La buena noticia es que los tres despliegan en Workers, y lo hacen a través de la misma pieza discreta: un adaptador. Entender qué es un adaptador y qué produce es lo que convierte “desplegar mi web en Cloudflare” de un ritual de configuración a un modelo mental claro.

El adaptador: un compilador hacia el Worker

Un framework full-stack tiene, en abstracto, dos mitades: un motor de renderizado que convierte tus componentes en HTML, y una capa de servidor que decide qué renderizar ante cada petición. Esa capa de servidor está escrita de forma neutral, sin comprometerse con ningún entorno concreto. El adaptador es el puente: en tiempo de build toma esa capa neutral y la reescribe para que hable el idioma del destino.

Para Cloudflare, “hablar el idioma del destino” significa una cosa muy concreta que ya conoces: producir un fetch handler. El adaptador no reinventa el framework; envuelve su servidor en la forma que el runtime de Workers sabe invocar, y coloca junto a él los assets estáticos que la web necesita.

npm create cloudflare@latest -- mi-app --framework=astro

Astro en Workers

Astro rinde por defecto a HTML estático, pero con el adaptador @astrojs/cloudflare y output: "server" pasa a renderizar bajo demanda dentro de un Worker. La configuración vive en astro.config.mjs y es deliberadamente escueta:

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";

export default defineConfig({
  output: "server",
  adapter: cloudflare(),
});

A partir de ahí, cada página .astro que no sea estática se renderiza en el servidor por petición, y los bindings de la plataforma aparecen en Astro.locals.runtime.env. Dentro de una página o de un endpoint de API accedes a tus recursos igual que en un Worker crudo, solo que a través del locals que Astro te entrega:

export async function GET({ locals }) {
  const { env } = locals.runtime;
  const valor = await env.CACHE.get("clave");
  return new Response(valor ?? "sin dato");
}

React Router y SvelteKit

El patrón se repite con variaciones de nombre. React Router v7 —el sucesor directo de Remix, con el que se fusionó a finales de 2024— despliega en Workers a través de su plantilla oficial de Cloudflare, apoyada en el plugin de Vite de la plataforma. Sus loader y action reciben un context desde el que alcanzas los bindings en context.cloudflare.env:

export async function loader({ context }: LoaderFunctionArgs) {
  const { env } = context.cloudflare;
  const { results } = await env.DB.prepare("SELECT * FROM posts").all();
  return { posts: results };
}

SvelteKit usa @sveltejs/adapter-cloudflare, y su convención para el entorno es event.platform.env. En un +page.server.ts o en un endpoint, el objeto platform que Cloudflare inyecta trae los bindings, el contexto de ejecución y la caché:

export async function load({ platform }) {
  const sesion = await platform.env.KV.get("sesion");
  return { sesion };
}

El destino común

Cuando das un paso atrás, los tres frameworks cuentan la misma historia. Cada uno tiene su motor de renderizado y su cultura —islas en Astro, loader y action en React Router, load en SvelteKit— pero todos, al pasar por su adaptador de Cloudflare, colapsan en la misma forma de salida: un Worker con un fetch handler más una carpeta de assets estáticos servidos desde el edge.

flowchart TB
A[Astro] --> AD1[adaptador cloudflare]
R[React Router v7] --> AD2[adaptador cloudflare]
S[SvelteKit] --> AD3[adaptador cloudflare]
AD1 --> W[Worker con fetch handler]
AD2 --> W
AD3 --> W
W --> AS[Assets estaticos en el edge]
style W fill:#fab387,color:#11111b

El plugin de Vite de Cloudflare cierra el círculo en desarrollo: hace que vite dev ejecute tu framework sobre workerd, el runtime real, en lugar de sobre Node. Así el entorno local deja de ser una imitación y pasa a ser el mismo motor que producción, con tus bindings emulados incluidos.