Almacenamiento en caché de rutas

Añadido en: astro@7.0.0 Nuevo

Astro proporciona una API independiente de la plataforma para almacenar en caché las respuestas de páginas y endpoints renderizados bajo demanda. Las directivas de caché establecidas en tus rutas se traducen en las cabeceras o comportamientos en tiempo de ejecución adecuados según el proveedor de caché configurado.

El almacenamiento en caché de rutas se basa en la semántica estándar de almacenamiento en caché de HTTP, incluyendo max-age y stale-while-revalidate, con soporte para invalidación basada en etiquetas y rutas, reglas de ruta a nivel de configuración y proveedores de caché acoplables que los adaptadores pueden establecer automáticamente.

Configurar almacenamiento en caché

El almacenamiento en caché de rutas requiere un proveedor de caché para determinar cómo se implementa la caché en tiempo de ejecución. Está disponible un proveedor interno en memoria, y se pueden implementar proveedores personalizados para casos de uso avanzados y entornos de ejecución específicos.

Para habilitar esta característica, establece un proveedor de caché en tu configuración de Astro:

import { defineConfig, memoryCache } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({ mode: 'standalone' }),
  cache: {
    provider: memoryCache(),
  },
});

Luego puedes usar Astro.cache en tus páginas .astro (o context.cache para rutas de API y middleware) para controlar el almacenamiento en caché por solicitud. Los valores predeterminados de caché para grupos de rutas también se pueden definir de forma declarativa en tu configuración utilizando routeRules.

Si despliegas en Netlify, Vercel o Cloudflare, puedes usar el proveedor de caché de CDN experimental de sus respectivos adaptadores en lugar del proveedor en memoria.

Proveedores de caché del adaptador

Los adaptadores oficiales de Astro para Netlify, Vercel y Cloudflare proporcionan cada uno un proveedor de caché de CDN experimental que asigna las directivas de caché a las cabeceras de caché nativas de la plataforma y a la API de invalidación. En lugar de almacenar las respuestas en memoria, estas envían tus directivas de caché a la red de borde (edge network) del host, y los aciertos de caché se sirven directamente desde la CDN sin invocar la función de tu servidor.

Durante la fase experimental, estos proveedores deben habilitarse manualmente, como se muestra a continuación. En una versión futura, los proveedores de Netlify y Vercel se habilitarán automáticamente mediante sus adaptadores. El proveedor de Cloudflare requiere una característica que actualmente se encuentra en beta privada.

Cada proveedor etiqueta automáticamente las respuestas almacenadas en caché con la ruta de la solicitud, de modo que cache.invalidate({ path }) funciona en plataformas que solo admiten purgas basadas en etiquetas.

Netlify

Añadido en: @astrojs/netlify@8.0.0 Nuevo

Importa cacheNetlify() desde @astrojs/netlify/cache y establécelo como tu proveedor de caché:

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';
import { cacheNetlify } from '@astrojs/netlify/cache';

export default defineConfig({
  adapter: netlify(),
  cache: {
    provider: cacheNetlify(),
  },
});

El proveedor establece las cabeceras Netlify-CDN-Cache-Control y Netlify-Cache-Tag. Las respuestas almacenadas en caché utilizan la caché duradera de Netlify para que se compartan en todos los nodos de borde, reduciendo las invocaciones de funciones. Se admite la invalidación tanto basada en etiquetas como en rutas.

Vercel

Añadido en: @astrojs/vercel@11.0.0 Nuevo

Importa cacheVercel() desde @astrojs/vercel/cache y establécelo como tu proveedor de caché:

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';
import { cacheVercel } from '@astrojs/vercel/cache';

export default defineConfig({
  adapter: vercel(),
  cache: {
    provider: cacheVercel(),
  },
});

El proveedor establece las cabeceras Vercel-CDN-Cache-Control y Vercel-Cache-Tag. Se admite la invalidación tanto basada en etiquetas como en rutas. La invalidación de etiquetas es una invalidación suave: las respuestas almacenadas en caché se marcan como obsoletas y se revalidan en segundo plano usando stale-while-revalidate.

Cloudflare

Añadido en: @astrojs/cloudflare@14.0.0 Nuevo

Importa cacheCloudflare() desde @astrojs/cloudflare/cache y establécelo como tu proveedor de caché:

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
import { cacheCloudflare } from '@astrojs/cloudflare/cache';

export default defineConfig({
  adapter: cloudflare(),
  cache: {
    provider: cacheCloudflare(),
  },
});

El proveedor establece las cabeceras Cloudflare-CDN-Cache-Control y Cache-Tag. El adaptador habilita el almacenamiento en caché de Workers automáticamente cuando se configura un proveedor de caché de Cloudflare. Se admite la invalidación tanto basada en etiquetas como en rutas.

Interactuar con la caché

El objeto cache proporciona métodos para establecer opciones de caché, invalidar entradas y comprobar el estado actual de la caché. Este objeto está disponible en tus páginas .astro como Astro.cache, y en las rutas de API y el middleware como context.cache.

Consulta la referencia de la API de caché para obtener más detalles.

Comprobar si el almacenamiento en caché está habilitado

Cuando el almacenamiento en caché no está configurado, cache.set(), cache.tags y cache.options registran una advertencia, y cache.invalidate() lanza un error. Para evitar esto, envuelve tu lógica de almacenamiento en caché en una comprobación condicional utilizando cache.enabled. Su valor siempre es false cuando no se ha configurado ningún proveedor o en el modo de desarrollo.

---
if (Astro.cache.enabled) {
  const tags = await getProductTags(Astro.params.id);
  Astro.cache.set({ maxAge: 3600, tags });
}
---

Establecer opciones de caché

Llama a cache.set() con un objeto de opciones para habilitar el almacenamiento en caché para la respuesta actual.

El siguiente ejemplo almacena en caché una página durante 2 minutos, sirve contenido obsoleto (stale) durante 1 minuto mientras se revalida, y etiqueta la respuesta para una invalidación dirigida:

---
export const prerender = false; // Not needed in 'server' mode

Astro.cache.set({
  maxAge: 120,
  swr: 60,
  tags: ['home'],
});
---

<html><body>Cached page</body></html>

En las rutas de API y el middleware, usa context.cache:

export function GET(context) {
  context.cache.set({
    maxAge: 300,
    tags: ['api', 'data'],
  });
  return Response.json({ ok: true });
}

Desactivar el almacenamiento en caché

Llama a cache.set() con false para desactivar explícitamente el almacenamiento en caché de una solicitud. Esto es útil cuando una regla de ruta coincidente almacenaría en caché la respuesta de lo contrario:

---
if (isPersonalized) {
  Astro.cache.set(false);
}
---

Leer el estado de la caché

Puedes acceder a las opciones de caché acumuladas actualmente a través de cache.options. Esto es útil para la depuración o cuando deseas modificar condicionalmente el almacenamiento en caché según el estado actual:

const { maxAge, swr, tags } = context.cache.options;

Invalidar entradas de caché

Puedes purgar las entradas almacenadas en caché por etiqueta o ruta utilizando cache.invalidate(). Esto es útil para borrar mediante programación el contenido almacenado en caché cuando queda obsoleto, como después de una actualización de contenido o una acción del usuario.

El siguiente ejemplo crea una ruta de API que invalida por etiqueta y por ruta:

export async function POST(context) {
  // Invalidate all entries tagged 'data'
  await context.cache.invalidate({ tags: ['data'] });

  // Invalidate a specific path
  await context.cache.invalidate({ path: '/api/data' });

  return Response.json({ purged: true });
}

La invalidación basada en etiquetas elimina todas las entradas almacenadas en caché cuyas etiquetas incluyan cualquiera de las etiquetas proporcionadas. La invalidación basada en rutas es solo para coincidencias exactas (no se admiten patrones glob ni comodines).

Comportamiento de fusión

Las múltiples llamadas a cache.set() dentro de una sola solicitud se fusionan de acuerdo con las siguientes reglas:

Valores escalares (maxAge, swr, etag): el último que se escribe gana
lastModified: la fecha más reciente gana
tags: se acumulan en todas las llamadas

El middleware, las plantillas (layouts), los cargadores de contenido (content loaders) y el código de la página pueden contribuir de forma independiente con directivas de caché.

Comportamiento en modo de desarrollo

En el modo de desarrollo, la API de caché está disponible para que el código de la ruta no necesite comprobaciones condicionales, pero no se realiza ningún almacenamiento en caché real. cache.enabled es false, y cache.set() y cache.invalidate() no realizan ninguna operación. Para probar tu almacenamiento en caché localmente, compila y luego previsualiza tu sitio.

Reglas de ruta

Las reglas de ruta te permiten definir el comportamiento de almacenamiento en caché para grupos de rutas de forma declarativa en tu configuración. Esto es útil para aplicar el almacenamiento en caché a grandes grupos de rutas a la vez.

El siguiente ejemplo almacena en caché todas las rutas de API con stale-while-revalidate, las páginas de productos con una ventana de frescura de 1 hora y las publicaciones de blog durante 5 minutos:

import { defineConfig, memoryCache } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({ mode: 'standalone' }),
  cache: {
    provider: memoryCache(),
  },
  routeRules: {
    '/api/[...path]': { swr: 600 },
    '/products/[...slug]': { maxAge: 3600, tags: ['products'] },
    '/blog/[...slug]': { maxAge: 300, swr: 60 },
  },
});

Se admiten los siguientes patrones de ruta:

Static paths: /about, /api/health
Dynamic parameters: /products/[id], /blog/[slug]
Rest parameters: /docs/[...path]

Los patrones utilizan la misma sintaxis, coincidencia y reglas de prioridad que el enrutamiento basado en archivos de Astro, por lo que los patrones más específicos tienen precedencia. No se admiten comodines glob como *; utiliza un parámetro [...rest] para que coincida con un grupo de rutas (por ejemplo, /api/[...path] para que coincida con todo lo que está bajo /api).

Las llamadas a cache.set() por ruta se fusionan con las reglas de ruta a nivel de configuración. El código de la ruta puede invalidar o ampliar los valores predeterminados establecidos en la configuración. Por ejemplo, una regla de ruta podría establecer un maxAge predeterminado para todas las páginas de productos, pero las páginas individuales pueden llamar a cache.set() para personalizar o deshabilitar el almacenamiento en caché según sea necesario.

Contribuir Comunidad Patrocinar