Bindings dentro del framework: alcanzar env

La pregunta que todo el mundo se hace al llevar un framework a Workers es la misma: “vale, pero ¿cómo llego a mi base de datos D1, a mi KV, a Workers AI?”. La respuesta tranquiliza: el framework no te esconde los bindings, te los entrega por su propia puerta. El objeto env que conociste en un Worker crudo sigue ahí, íntegro; solo cambia el lugar donde lo recoges. Aprender ese lugar en cada framework, y tiparlo bien, es todo lo que separa una app full-stack del acceso pleno a la plataforma.

El mismo env, muchas puertas

En un Worker crudo, env llega como segundo argumento del fetch handler. Cuando media un framework, ese argumento no desaparece: el adaptador lo captura y lo deposita en el objeto de contexto que el framework entrega a tus rutas de servidor. Por eso el acceso cambia de sintaxis pero no de fondo. Cada framework elige un nombre para esa puerta, y merece la pena tenerlos juntos:

Cuatro nombres, un solo objeto. Interiorizar que c.env, locals.runtime.env, context.cloudflare.env y platform.env son alias de la misma cosa te ahorra tratar cada framework como un mundo aparte. La plataforma es una; el framework solo decide en qué percha cuelga el llavero.

Acceder a D1, KV y AI

Con la puerta localizada, el uso de cada binding es idéntico al de un Worker crudo, porque los objetos que hay dentro de env son exactamente los mismos clientes vivos. Un loader de React Router que consulta D1, lee de KV e invoca Workers AI se ve así:

export async function loader({ context }: LoaderFunctionArgs) {
  const { env } = context.cloudflare;

  const usuario = await env.DB
    .prepare("SELECT * FROM usuarios WHERE id = ?")
    .bind(1)
    .first();

  const preferencias = await env.KV.get("prefs:1");

  const resumen = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
    prompt: "Resume el perfil del usuario en una linea",
  });

  return { usuario, preferencias, resumen };
}

El mismo trío en SvelteKit apenas cambia la puerta de entrada; los métodos prepare, get y run son idénticos porque los clientes lo son:

export async function load({ platform }) {
  const { results } = await platform.env.DB.prepare("SELECT * FROM posts").all();
  const cache = await platform.env.KV.get("home");
  return { posts: results, cache };
}

Y en un endpoint de Astro, la puerta es locals.runtime.env, pero lo que hay detrás vuelve a ser exactamente el mismo cliente de KV:

export async function GET({ locals }) {
  const { env } = locals.runtime;
  const banner = await env.KV.get("banner");
  return new Response(banner ?? "");
}

Compara los tres bloques y verás que la única línea que cambia entre frameworks es la que extrae env del contexto. A partir de ahí, prepare, bind, first, all, get y run son idénticos, porque los objetos que viven en env no saben ni les importa qué framework los invoca. Aprender esos métodos una vez basta para los cuatro.

Tipar para no ir a ciegas

Acceder a env sin tipos funciona, pero pierdes el autocompletado y la comprobación de errores, que es media razón de usar TypeScript. La herramienta canónica es wrangler types: lee tu wrangler.jsonc y genera una interfaz Env con cada binding y su tipo correcto, que luego conectas al contexto de tu framework.

wrangler types   # genera worker-configuration.d.ts con la interfaz Env

Cada framework tiene su forma de enganchar esa interfaz a su contexto —Astro y SvelteKit exponen tipos de runtime y platform que puedes extender con tu Env, y en Hono la pasas como parámetro genérico—, pero el origen de la verdad es siempre el mismo archivo generado. Regenéralo cada vez que añadas un binding y el editor te guiará por env como si fuera parte del lenguaje.

El descuido más común es dejar que ese archivo envejezca. Como no se regenera solo, si declaras un binding nuevo en wrangler.jsonc y olvidas volver a ejecutar wrangler types, el editor seguirá creyendo que no existe y te marcará un error donde no lo hay. La costumbre sana es encadenar la generación de tipos a un script previo al build o al arranque del entorno, de modo que los tipos nunca se separen de la configuración real que describe tus recursos.

flowchart LR
CFG[wrangler.jsonc con bindings] --> WT[wrangler types genera Env]
CFG --> AD[el adaptador conecta env al contexto]
WT --> CTX[contexto del framework tipado]
AD --> CTX
CTX --> USE[c.env / locals.runtime.env / platform.env]
style CTX fill:#89b4fa,color:#11111b
style USE fill:#a6e3a1,color:#11111b

Las reglas no cambian

Que un framework medie no deroga ninguna de las leyes del env que aprendiste con el Worker crudo. Siguen todas en pie, y olvidarlo produce bugs sutiles que el framework hace más difíciles de ver:

• env es estable por isolate y compartido entre peticiones: no guardes en él estado de una petición concreta.
• No hay entrada y salida fuera del contexto de una petición: no llames a env.DB ni a env.KV en el ámbito de módulo del framework, solo dentro de un loader, un load o un endpoint.
• Los bindings de datos son clientes vivos, no cadenas de texto: env.DB es un D1Database, no una URL de conexión.
• El acceso no cuesta reconexión: leer un binding cuantas veces quieras es gratis, porque ya está resuelto.