Astro + Cloudflare Pages para el workspace

ADR — Astro + Cloudflare Pages para el workspace

Contexto

CreaRackSL opera con separación clara entre producto principal (app de gestión de racks) y workspace interno: documentación, decisiones arquitectónicas, notas de agentes, bitácoras de proyecto. El workspace no requiere lógica de servidor compleja ni BD transaccional propia; su naturaleza es predominantemente documental y de consulta.

A inicios de 2026 se evaluó qué stack serviría mejor, priorizando despliegue sin fricción, coste mínimo y compatibilidad con el ecosistema Cloudflare ya adoptado (Workers, D1, R2).

Opciones evaluadas

• Next.js: conocido por el equipo, pero introduce modelo híbrido SSR/SSG con complejidad innecesaria para contenido estático. Despliegue óptimo apunta a Vercel, dependencia adicional.
• Remix: orientado a apps con formularios y mutaciones frecuentes; over-engineered para workspace documental.
• Django: descartado por requerir servidor Python persistente, coste operativo mayor y alejarse del stack JavaScript unificado.
• Astro: framework diseñado explícitamente para sitios content-first. Genera HTML estático por defecto con hidratación selectiva (“islands architecture”). Integración nativa con Cloudflare Pages via @astrojs/cloudflare.

Decisión

Astro 5.x desplegado en Cloudflare Pages. astro.config.mjs usa adaptador Cloudflare con output: 'static' como modo base, y wrangler.toml define pages_build_output_dir = "dist", apuntando al directorio de salida de Astro tras build. Despliegue vía integración Git nativa de CF Pages, sin pipeline CI externo.

Consecuencias

Positivas:

• Generación estática por defecto: tiempos de carga mínimos, sin cold starts.
• Distribución edge global vía red Cloudflare sin configuración adicional.
• Coste operativo cercano a cero en tier gratuito de Pages.
• Cohesión de plataforma: workspace comparte infraestructura con Workers y D1.
• Soporte nativo Markdown/MDX, idóneo para ADRs y documentación estructurada.

Negativas/limitaciones:

• Hidratación de componentes interactivos (islands) requiere disciplina: mezclar múltiples frameworks UI puede incrementar bundle si no se controla.
• Adaptador CF impone restricciones sobre ciertas APIs de Node.js en rutas con SSR parcial.
• Ecosistema de plugins más joven que Next.js; algunas integraciones requieren configuración manual.

Status

Accepted. Decisión vigente desde enero 2026. Revisión sugerida si workspace incorpora funcionalidades que requieran lógica de servidor significativa (auth, formularios complejos), momento de reevaluar uso del adaptador CF en modo hybrid o migración parcial a Workers.

Véase también

• [[decision—20260215—d1-biblioteca]]
• [[incident—20260315—cf-env-vars-next-deploy]] — footgun CF Pages env vars sin re-deploy