Guía completa de SSR en Astro: activa el renderizado en servidor en 3 pasos

Tu blog Astro vuela, Lighthouse por encima de 95, y de repente el jefe pide login de usuarios. ¿Cómo lo haces en un sitio estático? Abres la documentación y te llegan SSR, SSG, Hybrid y adapter de golpe.

La primera vez que toqué Astro SSR me pasó lo mismo. ¿No iba Astro de «rápido»? ¿SSR no lo ralentiza? ¿Vercel, Netlify o Node.js? ¿Qué significan output y prerender?

Configurar Astro SSR es más sencillo de lo que parece. En este artículo verás cuándo hace falta SSR (y no seguir solo con SSG), cómo configurar adaptadores y cómo mezclar SSR y SSG (modo Hybrid) en un proyecto. Al terminar podrás decidir si tu proyecto necesita SSR y tenerlo listo en unos 30 minutos.

Capítulo 1: Conceptos básicos de SSR y elección de stack

¿Cuándo necesitas SSR y no SSG?

El criterio más simple: ¿el contenido se define en el build o puede cambiar en cada visita?

SSG (Static Site Generation) es como un menú del día preparado por la mañana: el cliente llega y se sirve al instante. Artículos de blog, fichas de producto, «sobre nosotros»: contenido estable, SSG perfecto.

SSR (Server-Side Rendering) es cocinar bajo pedido: tras el login «Bienvenido de nuevo, Juan», cotizaciones en vivo, artículos en el carrito — cada usuario ve algo distinto; hace falta SSR.

¿Tu proyecto lo necesita? Si encajas en alguno de estos 5 escenarios, plantéate SSR:

1. Autenticación y contenido personalizado

El caso típico es el login. En build no sabes quién entrará ni qué nombre mostrar. En una plataforma de aprendizaje que monté, la home mostraba «Continuar: lección 5»; obligatorio SSR según el progreso del usuario.

2. Datos en tiempo real

Pronóstico, cotizaciones, marcadores. Cambian cada minuto; no reconstruyes el sitio cada minuto. Con SSR, cada visita trae datos frescos.

3. Consultas a base de datos

Búsqueda en e-commerce: cada palabra clave es distinta; no puedes pregenerar todas las páginas de resultados. SSR consulta la base al vuelo.

4. Rutas API

Formularios, subidas, llamadas a APIs de terceros requieren backend. El modo SSR de Astro permite rutas API (src/pages/api/xxx.js) sin un servidor aparte.

5. Pruebas A/B y recomendaciones personalizadas

Contenido según ubicación, hora o historial. La home de Taobao es el ejemplo: recomendaciones distintas por usuario; hace falta SSR.

Alguien preguntará: «¿Y la página de detalle del artículo con SSR?» Se puede, pero no compensa. El contenido es fijo; SSG + CDN es más rápido y barato. SSR no es obligatorio en todo.

Modo Hybrid: lo estático y lo dinámico

Astro 2.0 trajo Hybrid: SSG en páginas estáticas y SSR donde haga falta. Ejemplo e-commerce:

• Home, About, ayuda → SSG (carga rápida)
• Login, área de usuario, carrito → SSR (contenido dinámico)
• Ficha de producto → SSG (contenido fijo)
• Resultados de búsqueda → SSR (consulta en vivo)

Las páginas estáticas siguen igual de rápidas y las dinámicas funcionan bien. Un amigo usa SSG en listado y detalle del blog y SSR en comentarios; Lighthouse sigue en 95+.

Capítulo 2: Primeros pasos — 3 pasos para activar SSR

Configurar Astro SSR desde cero (adaptador Node.js)

Con claro que necesitas SSR, empecemos. Uso el adaptador Node.js: el más genérico, ideal para servidor propio o VPS.

Paso 1: instalar el adaptador en un comando

Astro ofrece configuración automática en la raíz del proyecto:

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

npx astro add node

Ese comando:

1. Instala @astrojs/node
2. Modifica astro.config.mjs
3. Actualiza dependencias en package.json

Verás marcas verdes en la terminal. Si prefieres manual (p. ej. fijar versión):

npm install @astrojs/node

Luego editas la config (siguiente paso).

Paso 2: editar la configuración

En astro.config.mjs, tras el comando automático verás algo así:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server', // activa SSR
  adapter: node({
    mode: 'standalone' // servidor independiente
  }),
});

Dos opciones clave:

output:

• 'static' (por defecto): todo SSG, HTML estático
• 'server': todo SSR, generación en cada petición
• 'hybrid': SSG por defecto, SSR por página (¡recomendado!)

mode:

• 'standalone': Astro arranca su propio servidor Node.js
• 'middleware': middleware integrable en Express, Koa, etc.

Suelo usar standalone: el servidor de Astro basta. Si ya tienes Express y quieres integrar Astro, usa middleware.

Paso 3: build y ejecución

npm run build

En dist/ aparece server/ con entry.mjs, entrada del servidor SSR.

Arrancar:

node ./dist/server/entry.mjs

Por defecto en http://localhost:4321. Todas las páginas pasan a SSR.

Depuración en desarrollo

No hace falta build en cada cambio:

npm run dev

El dev server soporta SSR con recarga en caliente.

Problemas frecuentes

1. Puerto ocupado: define otro puerto:

   PORT=3000 node ./dist/server/entry.mjs
   

2. No encuentra el módulo del adaptador: confirma @astrojs/node y ejecuta npm install

3. 404 en páginas: revisa src/pages/; las reglas de rutas de Astro siguen igual en SSR

En mi primera vez, de cero a servidor en marcha: menos de 5 minutos. En Vercel o Netlify hay adaptadores dedicados; el siguiente capítulo los detalla.

Capítulo 3: Adaptadores principales en detalle

Vercel, Netlify, Cloudflare: ¿cuál elegir?

Si despliegas en Vercel, Netlify o Cloudflare, SSR suele ser aún más simple: adaptadores oficiales y despliegue casi sin fricción.

Adaptador Vercel — serverless

Vercel es mi plataforma habitual: plan gratuito generoso y configuración mínima:

npx astro add vercel

Configuración típica:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'server',
  adapter: vercel(),
});

ISR (regeneración estática incremental) en Vercel

Primera visita: SSR; luego caché un tiempo; al expirar, regeneración. Útil cuando no necesitas datos frescos en cada petición.

adapter: vercel({
  isr: {
    expiration: 60, // caché 60 segundos
  },
}),

Un sitio de noticias puede actualizar la ficha cada minuto sin consultar la base en cada hit. ISR combina flexibilidad SSR y velocidad tipo SSG.

Despliegue en Vercel:

1. Configura el adaptador
2. Push a GitHub
3. Importa el proyecto en Vercel
4. Build: npm run build (autodetectado)
5. Despliega

Adaptador Netlify — Edge Functions

Netlify encaja bien en sitios estáticos con funciones dinámicas.

npx astro add netlify

// astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  output: 'server',
  adapter: netlify({
    edgeMiddleware: true, // middleware en edge
  }),
});

¿Qué es edgeMiddleware?

Ejecuta lógica de middleware (auth, redirecciones) en nodos edge, con menor latencia. Útil si el contenido depende de la ubicación del usuario.

Redirecciones en Netlify

Crea _redirects en la raíz:

/old-page  /new-page  301

Efecto al desplegar, sin tocar código.

Adaptador Cloudflare — CDN global

Usuarios repartidos por el mundo: Workers en 300+ centros de datos.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

npx astro add cloudflare

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

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});

Limitaciones de Cloudflare

El runtime de Workers no es Node.js puro: algunas APIs (p. ej. fs) no están disponibles. Si dependes de ellas, Cloudflare puede no encajar.

Tabla comparativa de adaptadores

Mi criterio:

• Blog, documentación: Vercel o Netlify
• E-commerce, SaaS: Vercel (ISR) o Node.js propio
• Producto internacional: Cloudflare
• Empresa: Node.js propio (privacidad y control)

No hay respuesta única: depende de tráfico y presupuesto. Mi blog va en Vercel; webs corporativas de clientes, a veces en servidor propio.

Capítulo 4: Hybrid en la práctica

SSR y SSG en un mismo proyecto

Tras el SSR puro, lo importante: modo Hybrid. Es la ventaja fuerte de Astro: velocidad SSG y flexibilidad SSR juntas.

Configurar Hybrid

Cambia output a 'hybrid':

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'hybrid', // SSG por defecto, SSR bajo demanda
  adapter: node(),
});

Por defecto todas las páginas son SSG; en las que necesites SSR añades una línea.

Control por página

// src/pages/dashboard.astro (SSR)

---

export const prerender = false; // sin prerender, usa SSR
const user = Astro.cookies.get('user');

---

<h1>Bienvenido de nuevo, {user?.name}</h1>
<p>Tienes {user?.notifications} mensajes sin leer</p>

prerender = false significa: no generar en build; renderizar cuando llegue la visita.

Si output es 'server' (todo SSR) y quieres SSG en una página:

// src/pages/about.astro (SSG)

---

export const prerender = true; // forzar generación en build

---

<h1>Sobre nosotros</h1>
<p>Contenido fijo, precargado, carga rapidísima.</p>

Resumen (para no confundirse):

Al principio me liaba; la regla: hybrid prioriza SSG, server prioriza SSR.

Caso práctico: blog + sistema de usuarios

Estructura ideal:

Estructura del proyecto:

src/pages/
├── index.astro          // home (SSG)
├── about.astro          // about (SSG)
├── blog/
│   ├── [slug].astro     // detalle (SSG)
│   └── index.astro      // listado (SSG)
├── login.astro          // login (SSR)
├── dashboard.astro      // área de usuario (SSR)
└── api/
    └── comments.js      // API comentarios (SSR)

Configuración:

// astro.config.mjs
export default defineConfig({
  output: 'hybrid', // SSG por defecto
  adapter: vercel(), // despliegue en Vercel
});

Páginas estáticas (sin config extra):

// src/pages/blog/[slug].astro

---

// sin prerender: por defecto SSG
import { getCollection } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;

---

<article>
  <h1>{post.data.title}</h1>
  <div set:html={post.body} />
</article>

Páginas dinámicas (SSR):

// src/pages/dashboard.astro

---

export const prerender = false; // activa SSR

// comprobar sesión
const token = Astro.cookies.get('token')?.value;
if (!token) {
  return Astro.redirect('/login');
}

// datos del usuario
const user = await fetch(`https://api.example.com/user`, {
  headers: { Authorization: `Bearer ${token}` }
}).then(res => res.json());

---

<div>
  <h1>Hola, {user.name}</h1>
  <p>Email: {user.email}</p>
  <p>Último acceso: {user.lastLogin}</p>
</div>

Rutas API (SSR automático):

// src/pages/api/comments.js
export async function POST({ request }) {
  const { articleId, content } = await request.json();

  await db.comments.insert({
    articleId,
    content,
    createdAt: new Date(),
  });

  return new Response(JSON.stringify({ success: true }), {
    status: 200,
    headers: { 'Content-Type': 'application/json' }
  });
}

export async function GET({ url }) {
  const articleId = url.searchParams.get('articleId');

  const comments = await db.comments.findMany({
    where: { articleId },
    orderBy: { createdAt: 'desc' }
  });

  return new Response(JSON.stringify(comments), {
    headers: { 'Content-Type': 'application/json' }
  });
}

Beneficios:

1. Páginas estáticas (artículos, home) siguen rapidísimas, Lighthouse 95+, CDN
2. Páginas dinámicas (usuario) con datos en vivo
3. Rutas API como backend sin servidor aparte
4. Build corto: solo prerender de estáticas

En un proyecto con 50 artículos y área de usuario, build ~20 s; estáticas al instante, dinámicas ~100 ms. Hybrid es, en la práctica, lo que más recomiendo.

Capítulo 5: Problemas frecuentes y buenas prácticas

Trampas al configurar SSR

He tropezado con varias; aquí van causas y soluciones.

Problema 1: Astro.clientAddress is only available when using output: 'server'

Causa: usas Astro.clientAddress (IP del cliente) con output: 'static'.

Solución:

// astro.config.mjs
export default defineConfig({
  output: 'server', // o 'hybrid'
  adapter: node(),
});

Astro.clientAddress, Astro.cookies, Astro.redirect() solo en modo SSR.

Problema 2: 404 en producción, OK en local

Causa: adaptador mal configurado o build/output incorrecto en la plataforma.

Solución:

Vercel:

• Build: npm run build
• Output: .vercel/output (automático)
• No sobrescribas rutas en vercel.json; deja que Astro las gestione

Netlify:

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

• Build: npm run build
• Publish: dist (estático) o .netlify (SSR)
• Si persiste 404, revisa netlify.toml:

  [build]
    command = "npm run build"
    publish = "dist"
  

Problema 3: páginas SSR lentas (>2 s)

Causa: servidor justo o consultas pesadas.

Solución:

1. Caché:

   // src/pages/api/news.js
   export async function GET() {
     const cached = await redis.get('news');
     if (cached) {
       return new Response(cached, {
         headers: {
           'Content-Type': 'application/json',
           'Cache-Control': 'public, max-age=60'
         }
       });
     }

     const news = await fetchNewsFromDB();
     await redis.set('news', JSON.stringify(news), 'EX', 60);

     return new Response(JSON.stringify(news), {
       headers: {
         'Content-Type': 'application/json',
         'Cache-Control': 'public, max-age=60'
       }
     });
   }
   

2. Optimizar consultas:

   • Índices
   • Menos JOIN
   • Solo campos necesarios

3. ISR en Vercel:

   adapter: vercel({
     isr: { expiration: 300 } // caché 5 minutos
   }),
   

Problema 4: variables de entorno no llegan al cliente

Causa: en Astro hay variables de servidor y de cliente.

Solución:

Servidor (páginas SSR, API):

const secret = import.meta.env.SECRET_KEY; // cualquier variable

Cliente (JavaScript en el navegador):

const apiUrl = import.meta.env.PUBLIC_API_URL; // prefijo PUBLIC_

.env:

SECRET_KEY=abc123          # solo servidor
PUBLIC_API_URL=https://api.example.com  # cliente y servidor

Problema 5: adapter.setApp is not a function

Causa: versiones incompatibles de Astro y adaptador.

Solución:

# actualizar
npm update astro @astrojs/node

# o versiones alineadas
npm install astro@latest @astrojs/node@latest

Mantener Astro y adaptadores actualizados suele evitarlo.

Resumen de buenas prácticas

1. Hybrid por defecto: salvo que todo sea dinámico, output: 'hybrid'
2. SSR selectivo: prerender = false solo donde haga falta
3. Estáticos en CDN: public/ para imágenes, CSS, JS
4. Caché/ISR en listados poco cambiantes
5. Separar env: secretos en servidor, PUBLIC_ para lo expuesto
6. Monitorizar: Vercel Analytics o GA en tiempos de respuesta SSR

Conclusión

En tres ideas:

1. SSR no lo es todo; úsalo cuando toque

No te emociones solo con SSR ni des por muerto SSG. Estáticas con SSG, dinámicas con SSR; Hybrid encaja en la mayoría. Blogs enteros en SSR suelen ir peor: el contenido no cambia y SSG + CDN gana.

2. El adaptador sigue la plataforma; la config es simple

Vercel/Netlify/Cloudflare: npx astro add [plataforma]. Servidor propio: npx astro add node en minutos. La práctica es más directa que la documentación.

3. Hybrid une velocidad y personalización

Es la esencia de Astro: Lighthouse 95+ en estáticas, funciones dinámicas donde hagan falta, build y costes controlados. Hybrid es mi primera opción en proyectos nuevos.

Próximos pasos

1. Probar ya: en tu proyecto Astro, npx astro add node, SSR en 5 minutos
2. Inventariar páginas: cuáles deben ser dinámicas y cuáles estáticas
3. Profundizar: Server Islands de Astro permiten componentes SSR dentro de páginas SSG

Si te atasacas, el Discord oficial de Astro responde rápido.

Último aviso: no sobreoptimices. Con poco tráfico (<10 000 PV/día), un sitio estático puede bastar; SSR añade complejidad. El stack debe servir al negocio.

¡Buena configuración! Si tienes dudas, comenta abajo.