Configurar el adapter y las APIs del runtime

Instalar un adapter es una línea, pero conectarlo bien es donde asoma el poder de cada plataforma. Esta lección baja a astro.config: cómo se combinan output y adapter con las opciones propias del adapter, cómo platformProxy permite que astro dev emule en tu máquina los bindings de Cloudflare —una base de datos D1, un almacén KV—, por qué la optimización de imágenes cambia en el edge cuando Sharp no puede correr, y cómo se alcanzan las APIs específicas del runtime a través de Astro.locals.runtime. Configurar el adapter no es rellenar opciones al azar: es negociar, opción por opción, cuánto poder de la plataforma tomas y cuánto acoplamiento aceptas a cambio.

adapter en astro.config, con sus opciones

La clave adapter recibe la función del adapter, y esa función acepta un objeto de opciones que ajusta su comportamiento. El output decide la política de renderizado —static con rutas dinámicas puntuales, o server con todo bajo demanda por defecto—; el adapter decide el destino. Juntos definen cómo y dónde corre tu sitio.

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

export default defineConfig({
  output: 'server',
  adapter: cloudflare({
    platformProxy: { enabled: true },
    imageService: 'cloudflare',
  }),
});

astro add deja esta clave con valores por defecto sensatos; tu trabajo posterior es afinar las opciones según lo que la plataforma ofrezca. Cada adapter documenta las suyas, pero dos familias de opciones aparecen una y otra vez: las que emulan el runtime en desarrollo y las que redirigen servicios —imágenes, sesiones— hacia lo que el destino sí soporta.

platformProxy: el runtime de la plataforma en tu máquina

Cloudflare expone recursos —KV, R2, D1, secretos, la información geográfica de la petición— a través de bindings que solo existen dentro de su runtime. Esos bindings se declaran en el fichero de Wrangler, y de ahí los toma tanto la plataforma real como la emulación local.

// wrangler.jsonc
{
  "kv_namespaces": [{ "binding": "MI_KV", "id": "..." }],
  "d1_databases": [{ "binding": "DB", "database_name": "prod" }]
}

En astro dev, sin más, esos bindings no están, y Astro.locals.runtime llega vacío. La opción platformProxy: { enabled: true } resuelve el desfase: usa Wrangler por debajo para levantar emulaciones locales de esos recursos y poblar Astro.locals.runtime como lo haría la plataforma real.

---
// una pagina bajo demanda en Cloudflare
const { env, cf, ctx } = Astro.locals.runtime;

const guardado = await env.MI_KV.get('clave');   // binding KV
ctx.waitUntil(registrarVisita(cf.country));       // trabajo diferido
---
<p>Servido desde {cf.city}</p>

Con platformProxy activo, ese código funciona igual en tu portátil que en producción: lees de un KV emulado, consultas el país de la petición, programas trabajo diferido con ctx.waitUntil. Sin él, tendrías que desplegar para probar cualquier cosa que toque un binding —un ciclo de desarrollo lento y a ciegas—.

Para que Astro.locals.runtime deje de ser any, su tipo se declara una vez en src/env.d.ts. El adapter de Cloudflare exporta un tipo Runtime parametrizado con tu Env —el que genera Wrangler a partir de tus bindings—, y lo enlazas a App.Locals:

// src/env.d.ts
type Runtime = import('@astrojs/cloudflare').Runtime<Env>;
declare namespace App {
  interface Locals extends Runtime {}
}

Imágenes y servicios que dependen del runtime

El servicio de imágenes de Astro usa por defecto Sharp, un módulo nativo de Node. En el edge no hay módulos nativos, así que optimizar imágenes bajo demanda ahí exige otro camino. El adapter de Cloudflare expone imageService para elegirlo, y ese menú resume el patrón general: cuando el runtime no soporta la implementación por defecto, el adapter ofrece una específica de la plataforma.

adapter: cloudflare({
  imageService: 'cloudflare', // redimensionado en el edge, sin Sharp
}),

La lección general trasciende las imágenes: cualquier capacidad que en Node dabas por sentada —procesar un PDF, comprimir con una librería nativa, leer una fuente del disco— hay que replantearla en el edge como un servicio de la plataforma o una llamada a una API externa. El adapter te dice qué tienes disponible; el runtime, qué te falta y por dónde suplirlo.

Trabajo diferido y sesiones en el runtime

El runtime no solo se lee: también difiere trabajo y guarda estado. ctx.waitUntil acepta una promesa que la plataforma mantiene viva después de enviar la respuesta —registrar una analítica, calentar un caché, escribir un log— sin retrasar al usuario ni un milisegundo. Y el almacenamiento del runtime puede respaldar a Astro: en Cloudflare, un binding KV sirve de trastienda al sistema de sesiones, de modo que Astro.session persiste entre peticiones usando la infraestructura de la propia plataforma.

---
const { ctx, env } = Astro.locals.runtime;
// responde ya y registra la visita despues, sin bloquear
ctx.waitUntil(env.LOGS.put(crypto.randomUUID(), JSON.stringify({ t: Date.now() })));
---

Estas APIs del runtime —los bindings, la geolocalización, el trabajo diferido, el almacenamiento— son puertas de poder, pero también son puntos de acoplamiento. Astro.locals.runtime.env no existe en Node ni en Vercel; cf.country es vocabulario de Cloudflare. Usarlas es legítimo y a menudo la razón misma de elegir esa plataforma, pero conviene saber que cada una es un hilo que te ata al destino.

flowchart TD
CFG[astro config con adapter y opciones] --> PP[platformProxy en dev]
CFG --> IMG[imageService del runtime]
CFG --> LOC[Astro locals runtime]
PP --> DEV[bindings emulados en tu maquina]
LOC --> ENV[env KV D1 R2 y secretos]
LOC --> CFO[cf geolocalizacion de la peticion]
LOC --> CTX[ctx waitUntil trabajo diferido]
style CFG fill:#89b4fa,color:#11111b
style LOC fill:#a6e3a1,color:#11111b