Caché y revalidación: Los 4 niveles de caché de Next.js

Por qué es importante#

En aplicaciones web de alto rendimiento, la latencia de la base de datos y de los microservicios externos determina directamente el TTFB y la experiencia de usuario. La ejecución descontrolada de consultas SQL reiteradas y peticiones HTTP agota los recursos de cómputo y satura los pools de conexiones.

El App Router de Next.js incorpora un sistema de caché de múltiples niveles que combina las capacidades del núcleo de React con el runtime de Next.js. Este sistema abarca todo el ciclo de vida del dato: desde la deduplicación en memoria RAM durante un único renderizado de servidor, hasta la persistencia distribuida en CDN de páginas estáticas y el almacenamiento en caché de segmentos de ruta en el navegador del cliente.

Comprender en profundidad cada capa de caché, sus fronteras de desoptimización y los mecanismos de invalidación bajo demanda distingue al desarrollador que sufre por datos obsoletos en producción del arquitecto que diseña sistemas distribuidos consistentes y de alta velocidad.

Modelo mental#

Next.js opera 4 niveles de caché independientes, cada uno con un cometido especializado, un alcance aislado y un ciclo de vida propio:

1. Request Memoization (React): Caché en la memoria RAM del servidor activa durante la generación de una única respuesta. Evita la duplicación de peticiones de red entre componentes de servidor aislados del mismo árbol.
2. Data Cache (Next.js): Almacenamiento persistente en el servidor (disco, KV o Redis) que conserva las respuestas HTTP y el resultado de cómputos complejos entre peticiones de distintos usuarios y sesiones.
3. Full Route Cache (Next.js): Caché en el servidor que almacena el documento HTML precompilado y el grafo binario RSC Flight Payload para rutas estáticas.
4. Client Router Cache (Next.js / Browser): Caché de segmentos de interfaz en la memoria RAM del navegador que permite transiciones instantáneas entre pantallas sin consultar al servidor (Soft Navigation).

Interactúa con el siguiente simulador para observar el tránsito de una petición a través de los 4 niveles de caché:

Sintaxis y API#

1. Request Memoization (React)#

React deduplica automáticamente las llamadas fetch con idéntica URL y las mismas opciones dentro del árbol de componentes de un mismo renderizado de servidor. La vida útil de esta memoria se limita a los milisegundos que dura la emisión de la respuesta.

[!IMPORTANT] Request Memoization no se comparte entre usuarios ni peticiones distintas. Es una optimización interna de un único ciclo de render de React Server Components. No existe una bandera global para apagarla, pero puede omitirse por llamada asignando un AbortController exclusivo (mediante la propiedad signal) a fetch.

// app/components/Header.tsx
export async function Header() {
  // Ejecuta la petición de red física real
  const user = await fetch('https://api.internal/user/me').then(r => r.json());
  return <header>Usuario: {user.name}</header>;
}

// app/components/Sidebar.tsx
export async function Sidebar() {
  // Se obtiene al instante de Request Memoization (RAM) sin emitir otra petición HTTP
  const user = await fetch('https://api.internal/user/me').then(r => r.json());
  return <aside>Rol: {user.role}</aside>;
}

2. Gestión de Data Cache#

En Next.js 15+, la llamada fetch estándar es sin caché por defecto (cache: 'no-store'). El almacenamiento en la Data Cache requiere configuración explícita.

// 1. Predeterminado en Next.js 15+: no-store (siempre obtiene datos frescos de la red)
const freshData = await fetch('https://api.internal/rates');

// 2. Caché persistente (se almacena indefinidamente hasta revalidación explícita)
const immutableData = await fetch('https://api.internal/dictionary', {
  cache: 'force-cache',
});

// 3. Time-based revalidation (Stale-While-Revalidate durante 60 segundos)
const catalog = await fetch('https://api.internal/products', {
  next: { revalidate: 60 },
});

// 4. Etiquetado de consultas para invalidación On-demand quirúrgica
const profile = await fetch('https://api.internal/user/10', {
  next: { tags: ['user-10', 'users'] },
});

3. Revalidación bajo demanda: revalidateTag y revalidatePath#

Para purgar datos obsoletos ante mutaciones (Server Actions, Webhooks), se utilizan las utilidades del módulo next/cache. Estas funciones invalidan de forma simultánea los registros en la Data Cache y los segmentos dependientes en la Full Route Cache.

'use server';

import { revalidatePath, revalidateTag } from 'next/cache';
import { db } from '@/lib/db';
import { products } from '@/lib/schema';
import { eq } from 'drizzle-orm';

export async function updateProductPrice(productId: string, newPrice: number): Promise<{ success: boolean }> {
  // 1. Mutar el registro en la base de datos principal
  await db.update(products).set({ price: newPrice }).where(eq(products.id, productId));

  // 2. Purga por etiqueta (invalida todas las consultas con este tag en toda la aplicación)
  revalidateTag(`product-${productId}`);
  revalidateTag('catalog-list');

  // 3. Invalidar la ruta específica
  revalidatePath(`/products/${productId}`, 'page');

  return { success: true };
}

Patrones prácticos#

Patrón 1: Stale-While-Revalidate (SWR) bajo el capó#

Al configurar la opción next: { revalidate: 60 }, el framework aplica el siguiente protocolo:

1. Petición en T = 0s (Cold Start): Fallo de caché. El servidor consulta a la fuente, responde al cliente y registra los datos en la Data Cache con su marca temporal.
2. Peticiones en T = 1..59s (Cache Hit): Todos los usuarios reciben la respuesta desde la Data Cache con latencias sub-milisegundo.
3. Petición en T = 60s+ (Stale Window): El dato se clasifica como obsoleto (stale). Next.js entrega de inmediato los datos cacheados (manteniendo un TTFB excelente) e inicia un worker en segundo plano para consultar la fuente de nuevo.
4. Peticiones en T = 62s+ (Cache Replaced): Tras completarse con éxito la consulta en segundo plano, la Data Cache se actualiza y los siguientes visitantes reciben los datos frescos.

Patrón 2: Caché de consultas SQL y ORMs con unstable_cache y 'use cache'#

Las consultas directas a base de datos (Prisma, Drizzle, pg) no emplean fetch global y quedan fuera de la Data Cache automáticamente. Para preservarlas se recurre a unstable_cache o a la directiva 'use cache' (Next.js 15.1+ con la bandera dynamicIO).

import 'server-only';
import { unstable_cache } from 'next/cache';
import { db } from '@/lib/db';
import { projects } from '@/lib/schema';
import { eq } from 'drizzle-orm';

export interface ProjectDTO {
  id: string;
  name: string;
  stars: number;
}

export const getCachedProject = (projectId: string) => {
  return unstable_cache(
    async (id: string): Promise<ProjectDTO | null> => {
      const record = await db.query.projects.findFirst({
        where: eq(projects.id, id),
      });
      return record ?? null;
    },
    ['project-detail-key', projectId], // Claves identificadoras
    {
      revalidate: 3600, // 1 hora
      tags: [`project-${projectId}`, 'projects'],
    }
  )(projectId);
};

Patrón 3: Exclusión y desoptimización de la Full Route Cache#

Una ruta pasa de generación estática (Static Generation) a renderizado dinámico por petición (Dynamic Rendering) si invoca APIs dependientes del contexto de la petición:

import { cookies, headers } from 'next/headers';

// Desactivar de forma forzada la Full Route Cache en todo el segmento
export const dynamic = 'force-dynamic';

export default async function AnalyticsPage() {
  // El acceso asíncrono a cabeceras y cookies en Next.js 15+ marca la ruta como estrictamente dinámica
  const headersList = await headers();
  const userAgent = headersList.get('user-agent') ?? 'unknown';

  const cookieStore = await cookies();
  const sessionId = cookieStore.get('sid')?.value;

  return (
    <main className="p-6">
      <h1>Analítica del sistema</h1>
      <p>Cliente: {userAgent}</p>
      <p>Sesión: {sessionId}</p>
    </main>
  );
}

Errores frecuentes#

// ❌ ERROR: Intentar leer cookies dentro de una función en caché
const getAuthData = unstable_cache(
  async () => {
    const cookieStore = await cookies(); // ¡Lanzará excepción DynamicServerError!
    return fetchUserData(cookieStore.get('token')?.value);
  },
  ['auth-user-key']
);

// ✅ CORRECTO: Pasa los datos dinámicos como parámetros explícitos incluidos en la clave
const getAuthData = (token: string) => 
  unstable_cache(
    async (authToken: string) => fetchUserData(authToken),
    ['auth-user-key', token]
  )(token);

// ❌ Error: La clave es estática, por lo que todos los clientes verán los datos del primer ID consultado
const getUser = unstable_cache(
  async (id: string) => db.query.users.findFirst(eq(users.id, id)),
  ['user'] 
);

// ✅ Correcto: El ID está integrado en la clave compuesta de la caché
const getUser = unstable_cache(
  async (id: string) => db.query.users.findFirst(eq(users.id, id)),
  ['user', id]
);

Análisis comparativo de los 4 niveles de caché#

Preguntas de entrevista#