Actualizado mayo 2026

Desplegar Astro en Cloudflare Pages: tutorial paso a paso

Q: ¿Qué es Astro y por qué es perfecto para Cloudflare Pages?

Astro es un generador de sitios estáticos moderno que produce HTML puro extremadamente rápido. Cloudflare Pages es ideal porque no necesita Node.js en servidor: Astro genera el HTML en build time, y Pages lo sirve desde la red edge de Cloudflare.

Q: ¿Cuál es el adaptador Cloudflare para Astro?

Es @astrojs/cloudflare. Se instala con npm install @astrojs/cloudflare y se configura en astro.config.mjs. El adaptador convierte tu proyecto Astro a un formato compatible con Workers y Pages.

Q: ¿Puedo usar variables de entorno en Astro + Cloudflare?

Sí. Las variables públicas (PUBLIC_*) se incluyen en el build HTML. Las privadas se guardan en .env y se usan solo en build time. Si necesitas secretos en runtime (Cloudflare Workers), usa wrangler.toml.

Q: ¿Qué es ISR y cómo lo uso con Astro + Cloudflare?

ISR (Incremental Static Regeneration) permite regenerar páginas dinámicamente después del deploy. Con Astro + Cloudflare Pages, usas Page Rules y Cloudflare Functions para invalidar caché y regenerar contenido sin redeploy completo.

Q: ¿Cómo ejecuto código en servidor (Edge Functions) con Astro?

Astro con el adaptador Cloudflare permite functions en la carpeta src/functions/. Se ejecutan en Cloudflare Workers (edge). Ideal para autenticación, validaciones, webhooks. El HTML estático se sirve ultrarrápido desde el CDN.

Astro genera HTML estático ultrarrápido. Cloudflare Pages lo sirve desde edge global sin costes de servidor. Guía completa: adaptador, configuración, deploy automático desde GitHub y edge functions.

⏱️ Lectura: 10 min 🚀 Deployment: 5 minutos 💰 Hosting: Gratis para siempre

¿Qué es Astro y por qué con Cloudflare Pages?

Astro es un generador de sitios estáticos (SSG) moderno que produce HTML puro extremadamente rápido. A diferencia de React o Next.js, Astro renderiza todo en build time, no en servidor:

✓ Sin JavaScript innecesario: Astro envía 0 JS por defecto. Solo añades JS cuando lo necesitas ("islands architecture")
✓ Soporte para componentes: React, Vue, Svelte, Preact... todos en el mismo proyecto, compilados a HTML estático
✓ Colecciones de contenido: Markdown, YAML, JSON organizados en esquemas tipados con TypeScript
✓ Rendimiento 100 Lighthouse: HTML puro, CSS optimizado, imágenes lazy-loaded por defecto

Cloudflare Pages es el home perfecto para Astro: sirve el HTML estático desde servidores edge en más de 300 ubicaciones globales. Resultado: latencia mínima desde cualquier parte del mundo, gratis.

Comparativa: Astro vs Next.js vs Hugo

Característica	Astro	Next.js	Hugo
Lenguaje	JavaScript/TypeScript	JavaScript/React	Go
Curva aprendizaje	Media (componentes + build)	Alta (React + SSR)	Baja (plantillas Go)
Performance	⭐⭐⭐⭐⭐ Óptima	⭐⭐⭐⭐ Buena	⭐⭐⭐⭐⭐ Óptima
Flexibilidad	Alta (componentes + API)	Muy alta (SSR + API)	Media (plantillas limitadas)
Hospedaje	Cloudflare Pages, Netlify, Vercel	Vercel, Cloudflare Pages, VPS	Cualquier hosting estático
Comunidad	Creciente (2024-2026)	Muy grande	Grande y madura

Resumen: Astro es ideal si buscas máximo performance sin complejidad. Hugo para blogs ultra-simples. Next.js cuando necesites SSR dinámico.

Paso 1: Instalar Astro localmente

Crear un nuevo proyecto Astro

Abre terminal y ejecuta:

&#123;$ npm create astro@latest my-awesome-site
&#123;$ cd my-awesome-site

El CLI te preguntará sobre el template. Para un sitio web genérico, elige "Basic". Astro instalará:

→ astro (core)
→ Node.js 18+ (ya deberías tenerlo)
→ npm dependencies (minimal)

Verificar que funciona localmente

&#123;$ npm run dev

Abre http://localhost:3000 y verás tu sitio Astro. Haz cambios en src/pages/index.astro y guarda para ver HMR (hot reload).

Paso 2: Instalar adaptador Cloudflare

Instalar @astrojs/cloudflare

&#123;$ npm install @astrojs/cloudflare --save

Configurar astro.config.mjs

Abre astro.config.mjs y reemplaza el contenido:

import &#123; defineConfig &#125; from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig(&#123;
  output: 'server',
  adapter: cloudflare(),
  integrations: [],
&#125;);

output: 'server' permite funciones dinámicas en Cloudflare. Si solo necesitas HTML estático, usa output: 'static'.

Paso 3: Configurar variables de entorno

Crear archivo .env.example

En la raíz del proyecto, crea .env (no commitear) y .env.example (para documenta):

# .env (local, no commit)
PUBLIC_API_URL=https://api.example.com
SECRET_API_KEY=your-secret-key-here

# .env.example (commit)
PUBLIC_API_URL=
SECRET_API_KEY=

Usar variables en componentes Astro

---
// src/pages/index.astro
const apiUrl = import.meta.env.PUBLIC_API_URL;
const secretKey = import.meta.env.SECRET_API_KEY; // Solo en servidor
---

<p>API URL: &#123;apiUrl&#125;</p>

PUBLIC_* se incluyen en el HTML compilado. SECRET_* solo existen en build time en el servidor.

Paso 4: Deploy automático desde GitHub

1. Conectar repositorio a Cloudflare Pages

a) Ve a dash.cloudflare.com → Pages
b) Haz clic en "Create a project"
c) Selecciona "Connect to Git" → autoriza GitHub
d) Elige tu repositorio

2. Configurar build settings

Cloudflare auto-detecta Astro, pero verifica:

→ Framework: Astro (auto-detectado)
→ Build command: npm run build
→ Output directory: dist
→ Node version: 18.x o superior

3. Añadir variables de entorno en Cloudflare

En la sección "Settings" de tu Pages project:

a) Environment variables → Production
b) Añade PUBLIC_API_URL y SECRET_API_KEY
c) Guarda y despliega. El siguiente push a main se construirá automáticamente

4. Deploy completado

Cloudflare Pages automáticamente:

✓ Clona tu repo
✓ Corre npm run build
✓ Despliega carpeta dist globalmente
✓ Asigna dominio (pages.dev o custom domain)

Paso 5: Edge Functions con Astro

Crear una función edge (API route dinámico)

En src/pages/api/hello.ts:

// src/pages/api/hello.ts
export const GET = async (&#123; request &#125;) => &#123;
  const message = 'Hola desde Cloudflare Edge';
  return new Response(JSON.stringify(&#123; message &#125;), &#123;
    status: 200,
    headers: &#123; 'Content-Type': 'application/json' &#125;,
  &#125;);
&#125;;

Accede a https://tu-sitio.pages.dev/api/hello y obtendrás JSON ejecutado en Edge.

Casos de uso reales para Edge Functions

→ Autenticación: Validar tokens JWT antes de servir contenido protegido
→ Webhooks: Recibir eventos (Stripe, GitHub, etc) e invalidar caché
→ A/B testing: Servir versiones distintas del HTML basado en headers
→ Redireccionamientos dinámicos: Rutas cortas personalizadas sin hardcode
→ Proxy seguro: Llamadas a APIs externas sin exponer claves

ISR (Regeneración Incremental) con Cloudflare

ISR permite regenerar páginas después del deploy sin un rebuild completo. Con Astro + Cloudflare:

1. Build time estático: Astro genera HTML para todas las páginas en npm run build

2. Webhook invalidador: Cuando tu CMS publica contenido nuevo (p.ej. blog post), envía webhook a una Cloudflare Function:

// Webhook handler (cloudflare function)
export const POST = async (&#123; request &#125;) => &#123;
  const payload = await request.json();
  const slug = payload.post_slug;

  // Invalida caché de esta página
  await fetch(`https://tu-sitio.pages.dev/purge`, &#123;
    method: 'POST',
    headers: &#123; 'X-CF-Purge-Token': 'tu-token' &#125;,
    body: JSON.stringify(&#123; files: [`/blog/$&#123;slug&#125;/`] &#125;),
  &#125;);

  return new Response('Caché invalidado', &#123; status: 200 &#125;);
&#125;;

3. Resultado: El siguiente request regenera la página desde el servidor edge. Usuarios ven contenido actualizado sin que esperes a un deploy completo.

Configuración wrangler.toml (opcional)

Si usas Cloudflare Workers avanzados, puedes crear wrangler.toml en la raíz:

# wrangler.toml
name = "my-astro-site"
type = "javascript"
compatibility_date = "2025-05-31"

[env.production]
routes = [
  &#123; pattern = "example.com/*", zone_name = "example.com" &#125;
]

[env.production.vars]
PUBLIC_API_URL = "https://api.example.com"

[[env.production.kv_namespaces]]
binding = "CACHE"
id = "your-kv-id"

Con esto puedes usar KV Storage para cachés persistentes, configurar routings avanzados, y secretos de producción.

Troubleshooting común

"Build failed: Cannot find module @astrojs/cloudflare" +

Solución: En Cloudflare Pages, ve a Settings → Environment variables y añade:

NODE_VERSION=18.17.0

Luego redeploy. Cloudflare necesita conocer la versión Node para instalar dependencias correctamente.

"Las variables de entorno no funcionan en el sitio desplegado" +

Comprueba que:

El variable es PUBLIC_* (si no, solo existe en build time)
Está definida en Cloudflare Pages Settings → Environment variables
Redeploy después de añadirla (el build anterior no la tenía)
No esté en .gitignore (el .env no debe commitarse, pero PUBLIC_* sí deben funcionar)

"El sitio es más lento de lo que espero" +

Pistas:

Usa npm run build && npm run preview para testear build localmente
Revisa Lighthouse Performance (PageSpeed Insights)
Imágenes: asegúrate de que son WebP/AVIF y tienen lazy loading
JS innecesario: Astro por defecto envía 0 JS, pero si usas componentes React, van con JS. Úsalos solo cuando necesites interactividad
CSS crítico: inline critical CSS, defer non-critical

"¿Puedo usar una base de datos con Astro + Cloudflare?" +

Sí, pero: Astro es SSG, se ejecuta en build time, no en request time. Opciones:

Para datos que cambian ocasionalmente: fetch en build time, regenera cada 24h
Para datos en tiempo real: usa edge functions + D1 (Cloudflare Database)
Para blogs: Markdown files + content collections (sin DB)
Para CMS: integrate Sanity / Contentful / Strapi, fetch en build + revalidate

Ventajas Astro + Cloudflare Pages vs otras opciones

⚡

Ultra-rápido por defecto: HTML puro, 0 JS innecesario. LCP < 1s sin esfuerzo.

💰

Gratis para siempre: Cloudflare Pages no tiene limitación de requests (a diferencia de Vercel/Netlify). Hosting + CDN global = $0.

🌍

Latencia global mínima: Red de Cloudflare en 300+ ciudades. Tus usuarios en Barcelona, São Paulo o Singapur todos con <50ms.

🔒

Seguridad incluida: SSL, DDoS protection, WAF... todo sin configurar.

🛠

Menor complejidad operativa: No tienes que gestionar Node.js en servidor. Todo es estático + funciones puntuales.

Preguntas frecuentes

¿Qué es Astro y por qué es perfecto para Cloudflare Pages? +

Astro es un generador de sitios estáticos moderno que produce HTML puro extremadamente rápido. Cloudflare Pages es ideal porque no necesita Node.js en servidor: Astro genera el HTML en build time, y Pages lo sirve desde la red edge de Cloudflare.

¿Cuál es el adaptador Cloudflare para Astro? +

Es @astrojs/cloudflare. Se instala con npm install @astrojs/cloudflare y se configura en astro.config.mjs. El adaptador convierte tu proyecto Astro a un formato compatible con Workers y Pages.

¿Puedo usar variables de entorno en Astro + Cloudflare? +