Regeneración estática incremental (ISR)

¿Qué es la regeneración estática incremental (ISR)?

La regeneración estática incremental (ISR, por Incremental Static Regeneration) sirve páginas estáticas prerrenderizadas y las actualiza en segundo plano después del despliegue, sin reconstruir todo el sitio. Cuando caduca la caché de una página, el siguiente visitante aún recibe la copia guardada mientras se genera una versión nueva, y los posteriores ven la actualizada. ISR es una función de Next.js y actúa por página, no por sitio.

Cómo funciona ISR

Imagina un blog con una ruta como /blog/[id]. La documentación de Next.js describe esta secuencia:

1. Con next build, Next.js prerrenderiza una página por cada id que devuelve generateStaticParams.
2. Las peticiones a esas páginas se sirven desde la caché y son muy rápidas.
3. Pasado el tiempo de revalidación (por ejemplo, 60 segundos), la siguiente petición todavía recibe la página en caché, ya obsoleta.
4. Esa misma petición dispara la regeneración de la página en segundo plano.
5. Cuando la nueva versión se genera con éxito, sustituye a la guardada y la siguiente petición la recibe.
6. Una página que no se prerrenderizó, como /blog/26, se genera bajo demanda la primera vez que se pide, si existe. Si no existe, la respuesta es un 404. El ajuste dynamicParams cambia este comportamiento.

Es el patrón stale-while-revalidate: primero la velocidad, poco después la frescura. Si la regeneración lanza un error, se sigue sirviendo la última página generada con éxito y Next.js lo reintenta en la siguiente petición.

Revalidación por tiempo y bajo demanda

La revalidación por tiempo da a una página una vida útil en segundos con la opción de segmento de ruta revalidate:

export const revalidate = 3600 // actualizar como máximo una vez por hora

La revalidación bajo demanda invalida una página cuando el contenido cambia de verdad, por ejemplo tras publicar una entrada. En el App Router se llama a revalidatePath o revalidateTag desde una Server Action o un Route Handler:

'use server'
import { revalidatePath } from 'next/cache'

export async function createPost() {
  // marcar la ruta /posts como obsoleta
  revalidatePath('/posts')
}

Ambas funciones invalidan la entrada de caché, y la regeneración ocurre en la siguiente petición, no al instante. La documentación recomienda un valor alto para la revalidación por tiempo, como una hora en lugar de un segundo, y la revalidación bajo demanda cuando se necesita más precisión.

ISR con Cache Components

Next.js documenta ahora dos modelos, y los pasos anteriores describen ISR sin Cache Components. Si cacheComponents está activado en la configuración de Next.js, se cachea con la directiva use cache y se da una vida útil a los resultados con cacheLife. Entonces ISR funciona de otro modo: para una URL que no figuraba en generateStaticParams, Next.js sirve al instante una App Shell genérica y la mejora en segundo plano cuando ya se conocen los parámetros. Según la documentación, la App Shell para parámetros no listados se sirve desde Next.js 16.3, y las versiones anteriores esperan a un renderizado completo en el servidor. Las notas de migración equiparan getStaticProps con revalidate a use cache con cacheLife. Comprueba qué modelo usa tu proyecto antes de copiar un ejemplo.

ISR frente a SSG y SSR

• La generación de sitios estáticos (SSG) construye cada página una vez durante el build, así que el contenido solo cambia al recompilar.
• ISR parte de páginas prerrenderizadas como SSG y las actualiza tras el despliegue, con un temporizador o bajo demanda.
• El renderizado en el servidor (SSR) renderiza en cada petición. Siempre está al día, pero el servidor trabaja cada vez salvo que haya una caché delante.

ISR encaja con contenido que cambia, pero no cada segundo: fichas de producto, artículos, documentación. Para datos por usuario o en tiempo real, la documentación de Next.js remite al renderizado dinámico. Esa salida estática es además lo que mejor cachea una red de distribución de contenidos (CDN). Para ver el framework completo, consulta Next.js.

Errores habituales

• Esperar frescura instantánea. El primer visitante tras la caducidad ve la página obsoleta. Si no es aceptable, usa revalidación bajo demanda o renderizado dinámico.
• Fijar un valor de revalidate muy corto. Un segundo regenera la página sin parar y anula el sentido de la salida estática.
• Ejecutar varias instancias con la caché por defecto. La caché del sistema de archivos es por instancia, así que la revalidación bajo demanda solo invalida la instancia que recibe la llamada. Usa un gestor de caché compartido personalizado.
• Usarla donde no está soportada. ISR requiere el runtime de Node.js y no funciona con exportación estática.
• Revalidar la ruta equivocada. Proxy no se ejecuta en las peticiones ISR bajo demanda, así que revalida la ruta exacta (/post/1, no la reescrita /post-1).
• Mezclar ajustes de fetch. Con varios fetch en una ruta gana el tiempo de revalidación más bajo, y un fetch con revalidate 0 o no-store hace la ruta dinámica.

Probar y monitorizar páginas con ISR

Una página en caché y una que se está regenerando se comportan de forma muy distinta, así que una prueba que solo pide URL calientes mide la caché y no tu servidor. Next.js añade la cabecera de respuesta x-nextjs-cache con los valores HIT, STALE, MISS o REVALIDATED, que indica por qué vía se atendió la petición. Regístrala en tus comprobaciones.

En una prueba de carga, incluye URL que nunca se prerrenderizaron o que acaban de caducar, porque la generación bajo demanda es donde suben los tiempos de respuesta, y compara percentiles de URL en caché y sin caché en vez de una media mezclada. Puedes hacer esa prueba con las pruebas de carga de LoadFocus y usar la monitorización de velocidad de página para seguir la velocidad según un calendario tras cada despliegue y cambio de contenido. Para las trampas de la invalidación, lee invalidación de caché y pruebas de rendimiento (artículo en inglés).

Preguntas frecuentes

¿Qué diferencia hay entre ISR y SSG?

SSG construye las páginas una vez durante el build. ISR parte de las mismas páginas prerrenderizadas, pero puede regenerar cada una después del despliegue, con un temporizador o cuando tú lo ordenes, así que no reconstruyes todo el sitio solo para cambiar una página.

¿El primer visitante ve contenido antiguo?

Sí. Cuando la revalidación por tiempo ha caducado, la siguiente petición recibe la página obsoleta en caché mientras Next.js la regenera en segundo plano. El visitante siguiente recibe la página nueva.

¿Puedo usar ISR con una exportación estática?

No. La documentación de Next.js indica que ISR no está soportado al crear una exportación estática y que requiere el runtime de Node.js.

¿ISR es lo mismo que Cache Components?

No, son dos modelos de caché. Con cacheComponents activado usas la directiva use cache y cacheLife, y ISR consiste en servir una App Shell para las URL no listadas y mejorarla en segundo plano. La opción revalidate a nivel de ruta pertenece al modelo sin Cache Components.

¿Cómo sé si una página salió de la caché?

Mira la cabecera de respuesta x-nextjs-cache. HIT significa servida desde caché, STALE servida desde caché mientras se revalida, MISS renderizada de nuevo y REVALIDATED regenerada mediante revalidación bajo demanda.