Astro Cache Provider API

Añadido en: astro@7.0.0 Nuevo

Astro Cache Provider API te permite configurar y gestionar el comportamiento de caching de rutas. Esta API incluye soporte integrado para un proveedor de caché en memoria y la capacidad de crear proveedores personalizados para varias estrategias de caching y runtimes.

¿Qué es un cache provider?

El comportamiento del caché está determinado por el cache provider configurado. Los proveedores se dividen en dos categorías:

Proveedores CDN

Los proveedores CDN traducen las directivas de caché en response headers (ej. CDN-Cache-Control, Cache-Tag) y dependen de un CDN o reverse proxy para manejar el caching. Estos headers internos se eliminan antes de que la respuesta llegue al cliente.

Un proveedor CDN implementa setHeaders() para producir los headers apropiados.

Proveedores de runtime

Los proveedores de runtime implementan onRequest() para interceptar peticiones y cachear respuestas en proceso. Añaden un response header X-Astro-Cache para observabilidad:

• HIT: respuesta servida desde caché
• MISS: respuesta renderizada fresca y almacenada en caché
• STALE: respuesta stale servida mientras se revalida en segundo plano

Proveedor de caché en memoria integrado

Astro incluye un proveedor de caché runtime LRU en memoria integrado adecuado para despliegues de instancia única. Importa memoryCache() desde astro/config:

astro.config.mjs

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

export default defineConfig({
  cache: {
    provider: memoryCache({ max: 500 }),
  },
});

Opciones de memoryCache()

Type: { max?: number; query?: object }
Default: { max: 1000 }

Configura el proveedor de caché en memoria.

max

Type: number
Default: 1000

Define el número máximo de entradas a mantener en caché. Cuando el caché excede este límite, la entrada menos recientemente usada es evacuada.

query

Type: { sort?: boolean; include?: string[]; exclude?: string[]; }

Controla cómo se manejan los parámetros de búsqueda en las cache keys.

query.sort

Type: boolean
Default: true

Determina si los parámetros de búsqueda deben ordenarse alfabéticamente. Esto es útil cuando el orden de los parámetros es significativo y para asegurar que su orden no afecte la cache key.

Establece en false para desactivar la ordenación y cachear URLs con diferentes órdenes de parámetros de búsqueda por separado.

query.exclude

Type: string[]
Default: ['utm_*', 'fbclid', 'gclid', 'gbraid', 'wbraid', 'dclid', 'msclkid', 'twclid', 'li_fat_id', 'mc_cid', 'mc_eid', '_ga', '_gl', '_hsenc', '_hsmi', '_ke', 'oly_anon_id', 'oly_enc_id', 'rb_clickid', 's_cid', 'vero_id', 'wickedid', 'yclid', '__s', 'ref']

Lista los parámetros de búsqueda a excluir de la cache key. Esto soporta wildcards glob (ej. "utm_*") y, por defecto, excluye parámetros comunes de tracking y analítica.

Establece en [] para incluir todos los parámetros de búsqueda en la cache key:

astro.config.mjs

memoryCache({
  query: { exclude: [] },
});

Se lanza un error si se usa junto con include.

query.include

Type: string[]

Lista los nombres de parámetros de búsqueda a incluir en la cache key. Cuando se establece, todos los demás parámetros se ignoran, incluyendo las exclusiones de parámetros de tracking por defecto.

El siguiente ejemplo solo usa los parámetros page y sort en la cache key, ignorando todos los demás:

astro.config.mjs

memoryCache({
  query: { include: ['page', 'sort'] },
});

Se lanza un error si se usa junto con exclude.

Comportamiento de cache key

El proveedor de memoria normaliza automáticamente las cache keys para mejores tasas de acierto:

• Ordenación de parámetros de búsqueda: Los parámetros se ordenan alfabéticamente, así que /page?b=2&a=1 y /page?a=1&b=2 resuelven a la misma entrada de caché.
• Exclusión de parámetros de tracking: Los parámetros comunes de analítica y tracking (ej. utm_source, fbclid, gclid) se excluyen de la cache key por defecto. Esto evita la fragmentación del caché por enlaces de marketing sin afectar el contenido de tu página.
• Soporte de header Vary: Cuando una respuesta incluye un header Vary, el proveedor de memoria usa los valores de los headers de petición especificados para crear entradas de caché separadas para cada variante. Por ejemplo, una respuesta con Vary: Accept-Language cacheará diferentes versiones para diferentes idiomas.

Nota

El header Cookie siempre se ignora para el keying de caché basado en Vary porque tiene una cardinalidad extremadamente alta (cada usuario típicamente tiene cookies diferentes), haciéndolo efectivamente no cacheable.

Escribir un cache provider personalizado

Un cache provider tiene dos partes:

1. El módulo de runtime — Un archivo que exporta por defecto una función CacheProviderFactory. Este módulo se empaqueta en tu output SSR, por lo que debe ser agnóstico al runtime: evita módulos integrados de Node.js (ej. node:fs, node:path) a menos que tu runtime objetivo los soporte.

2. El helper de configuración — Una función exportada para que los usuarios la llamen en astro.config.mjs. Devuelve un objeto CacheProviderConfig que le indica a Astro dónde encontrar el módulo de runtime y qué opciones pasarle. Este es el mismo patrón usado por el proveedor integrado memoryCache().

El siguiente ejemplo muestra un helper de configuración que acepta opciones tipadas y apunta a un módulo de runtime:

my-provider/config.ts

import type { CacheProviderConfig } from 'astro';

interface MyProviderOptions {
  apiKey: string;
  region?: string;
}

export function myCache(options: MyProviderOptions): CacheProviderConfig {
  return {
    entrypoint: 'my-provider/runtime', // resolved from the project root
    config: options, // passed to the factory at runtime
  };
}

El helper de configuración es entonces llamado en la configuración de Astro:

astro.config.mjs

import { defineConfig } from 'astro/config';
import { myCache } from 'my-provider/config';

export default defineConfig({
  cache: {
    provider: myCache({ apiKey: '...' }),
  },
});

El módulo de runtime exporta por defecto una factory que recibe la config serializada y devuelve un CacheProvider:

my-provider/runtime.ts

import type { CacheProviderFactory } from 'astro';

const factory: CacheProviderFactory = (config) => {
  return {
    name: 'my-cache-provider',

    // CDN-style: translate cache options into response headers
    setHeaders(options) {
      const headers = new Headers();
      if (options.maxAge !== undefined) {
        let value = `max-age=${options.maxAge}`;
        if (options.swr !== undefined) {
          value += `, stale-while-revalidate=${options.swr}`;
        }
        headers.set('CDN-Cache-Control', value);
      }
      if (options.tags?.length) {
        headers.set('Cache-Tag', options.tags.join(','));
      }
      return headers;
    },

    // Runtime-style: intercept requests (optional)
    async onRequest(context, next) {
      // Check cache, call next(), store response...
      return next();
    },

    // Handle invalidation requests
    async invalidate(options) {
      // Purge by tags or path...
    },
  };
};

export default factory;

Al escribir un proveedor CDN, Astro proporciona utilidades compartidas para construir cache-control headers y tags de invalidación basados en path.

Utilidades de cache provider

Astro exporta helpers compartidos para autores de proveedores CDN desde astro/cache/provider-utils. Estos son los mismos helpers usados por los proveedores first-party de Netlify, Vercel, y Cloudflare.

import {
  buildCacheControlDirectives,
  pathTag,
  setConditionalHeaders,
  collectInvalidationTags,
  normalizeTags,
} from 'astro/cache/provider-utils';

buildCacheControlDirectives()

Type: (options: CacheOptions, extraDirectives?: string[]) => string | undefined

Construye un string de directiva cache-control (ej. "public, max-age=300, stale-while-revalidate=60") a partir de CacheOptions, sin un nombre de header para que cada proveedor pueda aplicar el suyo (como Netlify-CDN-Cache-Control o Cloudflare-CDN-Cache-Control). Pasa extraDirectives para anteponer directivas de plataforma como public o durable. Devuelve undefined cuando no hay directivas de caching.

pathTag()

Type: (path: string) => string

Genera un cache tag para un path dado (astro-path:{path}). Usado para soportar invalidate({ path }) en plataformas que solo ofrecen purga basada en tags.

setConditionalHeaders()

Type: (headers: Headers, options: CacheOptions) => void

Establece los headers Last-Modified y ETag en un objeto Headers a partir de los valores correspondientes de CacheOptions.

collectInvalidationTags()

Type: (options: InvalidateOptions) => string[]

Recopila todos los tags necesarios para invalidar las opciones dadas, incluyendo el path tag cuando options.path está establecido. Usado por proveedores que implementan invalidación por path vía tags en lugar de purga nativa por path.

normalizeTags()

Type: (tags: string | string[] | undefined) => string[]

Normaliza un valor de tag a un array plano de strings.

Referencia de tipos de cache provider

Los siguientes tipos pueden importarse desde el módulo astro:

import type {
  CacheOptions,
  CacheProvider,
  CacheProviderConfig,
  CacheProviderFactory,
  InvalidateOptions,
} from "astro";

CacheOptions

Describe las opciones pasadas a un cache provider.

Aprende cómo usar las opciones de caché para controlar el comportamiento del caching.

CacheOptions.maxAge

Type: number

Define el tiempo en segundos durante el cual la respuesta se considera fresca.

CacheOptions.swr

Type: number

Especifica la ventana stale-while-revalidate en segundos. Se sirve contenido stale mientras se genera una respuesta fresca en segundo plano.

CacheOptions.tags

Type: string[]

Una lista de cache tags para invalidación dirigida. Los tags se acumulan a través de múltiples llamadas a cache.set().

CacheOptions.lastModified

Type: Date

Indica la fecha de modificación más reciente. Cuando múltiples llamadas a cache.set() proporcionan lastModified, la llamada más reciente tiene prioridad.

CacheOptions.etag

Type: string

Especifica el entity tag para peticiones condicionales.

CacheProvider

Describe un proveedor usado para caching. Esto requiere las propiedades name e invalidate() y acepta propiedades opcionales.

CacheProvider.name

Type: string

Un nombre único para el proveedor, usado en logs y para identificación.

CacheProvider.setHeaders()

Type: (options: CacheOptions, request: Request) => Headers

Traduce las opciones de caché en response headers. Esto se llama después de que la respuesta se renderiza pero antes de que se envíe al cliente. Estos headers se eliminan de la respuesta final.

La request entrante se pasa como segundo argumento para que un proveedor pueda leer la URL o los headers de la petición. Esto puede ser útil para auto-tagear respuestas con su pathname para invalidación basada en path.

CacheProvider.onRequest()

Type: (context: { request: Request; url: URL; waitUntil?: (promise: Promise<unknown>) => void }, next: MiddlewareNext) => Promise<Response>

Intercepta peticiones para implementar caching de runtime. El context incluye una función waitUntil() (cuando está disponible en el runtime) para trabajo en segundo plano como stale-while-revalidate.

CacheProvider.invalidate()

Type: (options: InvalidateOptions) => Promise<void>

Maneja peticiones de purga por tag o path.

CacheProviderConfig

Type: { entrypoint: string | URL; config?: Record<string, any> }

El objeto de configuración pasado a cache.provider. Usa una función helper (ej. memoryCache()) para una configuración con tipado seguro.

CacheProviderFactory

Type: (config: Record<string, any> | undefined) => CacheProvider

El tipo de función factory. Recibe el objeto de configuración serializable del proveedor desde la configuración de Astro.

InvalidateOptions

Describe las opciones pasadas al método invalidate() del proveedor.

InvalidateOptions.path

Type: string

Path exacto a invalidar. Sin soporte de glob o wildcard.

InvalidateOptions.tags

Type: string | string[]

Tag o tags a invalidar. Todas las entradas con tags coincidentes son purgadas.