Nuxt Multi Cache

Nuxt Multi Cache is an advanced caching solution for Nuxt applications that provides four primary capabilities:

• Component Cache: Caches the rendered markup of components to significantly reduce server-side rendering (SSR) time.
• Route Cache: Caches the full response of pages or custom API routes, including HTTP headers.
• Data Cache: A generic composable used to cache arbitrary data, such as external API responses or expensive computations.
• CDN Headers: Allows dynamic management of Cache-Control or Cache-Tag HTTP headers for edge caches like Cloudflare, Fastly, or Varnish.

It also provides a cache management API for purging specific items by key or using cache tags.

The nuxt-multi-cache module uses unstorage to manage the cache layer. By default, it uses the memory backend.

Important: If your Nuxt application runs in multiple instances (e.g., in a load-balanced environment), you should avoid the default memory backend. Using memory cache means that purging a cache via the API will only affect the specific instance that received the request, leaving other instances with stale data. To ensure consistency across all instances, use an external cache backend like Redis.

The module follows an opt-in approach. Simply installing the module does not enable any caching.

Features are managed through a two-step process:

1. Added: The feature is included in your application build (e.g., composables and components are available).
2. Enabled: The feature is active and performs its actual functionality (e.g., performing the caching).

This allows you to include composables in your code while disabling the actual caching logic during local development or debugging. You can control this via nuxt.config.ts or runtime config.

Important: Not all configuration options can be set in nuxt.config.ts. Options that must be bundled in the server build must be passed via the server options configuration file.

To ensure useCachedAsyncData works correctly, follow these rules:

1. Avoid side effects: Do not mutate external values inside the handler or the transform method. Since these functions are not executed when data is retrieved from the cache, any side effects they contain will be skipped on cache hits.
2. Ensure unique keys: The key argument is used directly as the cache identifier. If you use the same key for two different fetch operations, the second operation will return the cached data from the first, leading to unexpected behavior.

Cache tags are unique identifiers (e.g., article:235, language:de, image:313) assigned to cached items. They allow you to invalidate multiple related items across different cache layers (Component, Data, and Route) simultaneously. Instead of purging specific keys, you purge a tag, and all items associated with that tag are removed from the cache.

By default, tag invalidation is not immediate but occurs after a configurable delay defined by api.cacheTagInvalidationDelay in the module options.

The module calculates the exact expiration time using a single timestamp determined during the first cache interaction of a request, which is then stored in the event context.

Internally, the module handles time in two ways:

1. Seconds: Used for values representing an age (duration).
2. Unix Timestamp (seconds): Used for specific points in time.

When you set a max age (as seconds or a named duration), the module internally converts this into an expires property, which is a Unix timestamp representing the exact moment the item must be revalidated.

You can override certain module options at runtime using Nuxt runtime configuration (environment variables).

Important Constraint: You can only enable features via runtime config that are already enabled in the primary module configuration. For example, if route caching is disabled in your nuxt.config, you cannot enable it using NUXT_MULTI_CACHE_ROUTE=true. Runtime config is primarily used to toggle features off or enable debug mode in specific environments.

While Nuxt/Nitro provides built-in caching via routeRules and defineCachedEventHandler, nuxt-multi-cache provides different capabilities:

When to use nuxt-multi-cache: Use it if you need to decide cacheability dynamically during a request (e.g., a 'kill switch' if a backend fails during SSR) or if you need to manage cache tags/TTL per request.

The Route Cache and CDN Cache Control Headers features in nuxt-multi-cache operate independently. You can use them simultaneously to control both local server-side caching and edge/CDN caching.

Important: Setting a max-age via useRouteCache does not automatically update the max-age of the CDN cache control header, and vice versa. You must configure the expiration/visibility for both independently if you want them to align.

By default, API endpoints require authorization. You can authorize requests in three ways:

1. Token-based (Default): Provide a token in the x-nuxt-multi-cache-token header. You can set this token via the NUXT_MULTI_CACHE_API_AUTHORIZATION_TOKEN environment variable.
2. Custom Callback: Implement a custom check in multiCache.serverOptions.ts using defineMultiCacheOptions.
3. Disabled: Set api.authorization to false in nuxt.config.ts. Warning: Only do this if the endpoints are not accessible publicly!

fetch('http://localhost:3000/__nuxt_multi_cache/purge/component', {
  method: 'POST',
  headers: {
    'x-nuxt-multi-cache-token': 'hunter2',
  },
  body: JSON.stringify(['Navbar::de--chf']),
})