Blog Leonardo Leão
Arquitetura

Edge SSR com Astro 6 e Cloudflare D1: padrões e armadilhas

Astro 6 com adapter Cloudflare e D1 viabiliza SSR global sub-100ms, mas exige disciplina em cache HTTP, agregação de queries e uso correto de waitUntil para tarefas em background.

Por Publicado em 6 min de leitura
Edge SSR com Astro 6 e Cloudflare D1: padrões e armadilhas

Principais conclusões

  1. 01Astro 6 SSR + Cloudflare Workers entrega TTFB 30–80ms global sem rebuild.
  2. 02API antiga Astro.locals.runtime.env foi removida — use import { env } from cloudflare:workers.
  3. 03Cache-Control HTTP é a forma mais barata de baixar custo de Worker invocations.
  4. 04D1 não escala JOIN pesado — denormalize ou use KV/Cache API como camada extra.
  5. 05waitUntil() libera resposta enquanto pings IndexNow/Google rodam em background.

Por que edge SSR ganha de SSG para conteúdo dinâmico

SSG é imbatível para páginas que mudam pouco — você gera HTML uma vez e o CDN serve a velocidade da luz. Mas blogs com publicação frequente, listagem por categoria e busca pagam um preço alto: cada novo artigo dispara rebuild + redeploy. Em escala, isso vira o gargalo.

Edge SSR resolve isso renderizando sob demanda no datacenter mais perto do usuário. Com Cloudflare Workers + D1, o tempo até o primeiro byte fica em torno de 30–80ms globalmente, sem rebuild.

Como configurar Astro 6 com adapter Cloudflare

O ponto crítico é entender que Astro 6 mudou como o ambiente é exposto. A API antiga Astro.locals.runtime.env foi removida; agora você importa direto de cloudflare:workers.

Bindings e platformProxy

Em desenvolvimento, ative platformProxy no adapter para que astro dev tenha acesso ao D1 local via miniflare. Em produção, os bindings vêm direto do wrangler.toml.

Padrões de cache que funcionam na edge

Cache na edge é regido por headers HTTP padrão. As três regras que economizam mais dinheiro: (1) use Cache-Control: public, max-age=N generoso em rotas estáveis (sitemap, llms.txt, robots.txt); (2) use no-store em health checks; (3) nunca cache rotas autenticadas.

Armadilhas comuns com D1

D1 é SQLite na edge — a maior parte dos padrões SQL funciona, mas tem limites. Queries pesadas com JOIN em milhões de rows não escalam — prefira denormalização ou uma cache layer separada (KV ou Cache API). E lembre que cada query roda no datacenter de origem do D1, não na edge — isso adiciona ~30ms para usuários longe do datacenter primário.

Tarefas em background com waitUntil

Quando você publica um artigo, precisa pingar IndexNow e o sitemap do Google. Esses pings podem demorar 500ms — bloquear a resposta do publish é caro. A solução é waitUntil(): você devolve a resposta ao cliente imediatamente e o Worker continua executando o ping em background.

#astro #cloudflare #edge #d1 #ssr

Perguntas frequentes

Edge SSR substitui SSG para sempre?
Não. Páginas com conteúdo realmente estático ainda ganham com SSG ou ISR. Edge SSR brilha em listings dinâmicos, busca e personalização leve.
Qual o limite prático do D1 hoje?
D1 funciona bem até centenas de milhares de rows com queries simples. Acima disso, denormalize ou mude para Postgres gerenciado (Neon, Hyperdrive).
Como migrar de Astro 5 para 6 sem quebrar?
O ponto mais frequente é o env: substitua Astro.locals.runtime.env por import direto de cloudflare:workers em todos os endpoints e middleware.
Posso usar Drizzle ORM com D1?
Sim — adicione compatibility_flags = ["nodejs_compat"] no wrangler.toml para o Drizzle conseguir importar node:async_hooks.

Sobre o autor

Equipe Editorial

Equipe responsável pela curadoria, revisão e publicação de artigos técnicos no blog.

Seguir