Appearance
Configuration
nuxt-multi-cache follows an "opt-in" approach, meaning: Just installing the module will not add any caching to your app.
WARNING
Not all configuration options are available via nuxt.config.ts! Some have to passed via the server options configuration file, as they need to be bundled in the server build (which is not possible via nuxt.config.ts).
Adding and Enabling Features
A feature can be added and/or enabled, meaning:
- added: The feature is generally added and available in your app (such as composables or components)
- enabled: The feature is enabled and will perform its functionality (such as caching)
This "two step" approach allows you to generally add a composable like useDataCache, while allowing you to disable the actual caching which is very likely the case during local development or when debugging on deployed applications. It's also possible to enable or disable a feature via runtime config.
Example
This adds all composables for the data cache and also enables all caching:
typescript
export default defineNuxtConfig({
modules: ['nuxt-multi-cache'],
multiCache: {
data: {
enabled: true,
},
},
})This will still add all composables, but disable actual caching:
typescript
export default defineNuxtConfig({
modules: ['nuxt-multi-cache'],
multiCache: {
data: {
enabled: false,
},
},
})None of the composables are added, therefore it's not possible to use the data cache at all:
typescript
export default defineNuxtConfig({
modules: ['nuxt-multi-cache'],
multiCache: {},
})Full example
This example uses every possible configuration option.
typescript
export default defineNuxtConfig({
modules: ['nuxt-multi-cache'],
multiCache: {
// Component cache is enabled.
component: {
enabled: true,
},
// Data cache enabled.
data: {
enabled: true,
},
// Route cache is disabled. But because the `route` property is set the
// useRouteCache composable is still added to the build, it just doesn't
// cache.
route: {
enabled: false,
// Add a Cache-Status header that says how the route cache handled the
// request. A string sets the name of the cache in the header.
// Default: false
cacheStatus: true,
},
// CDN Cache Control Headers feature.
cdn: {
enabled: true,
// Set custom cache control for Cloudflare.
// Default: 'Surrogate-Control'
cacheControlHeader: 'CDN-Cache-Control',
// Set custom cache tags header for Cloudflare.
// Default: 'Cache-Tag'
cacheTagHeader: 'Cache-Tag',
},
// Cache Management API.
api: {
enabled: true,
// Use a different prefix for the API endpoints.
// Default: '/__nuxt_multi_cache'
prefix: '/api/nuxt-multi-cache',
// Disable authorization check on the API.
authorization: false,
// Cache tag invalidations should be buffered for 5 minutes before the
// cache items are actually purged.
// Default: 60000 (1 minute)
cacheTagInvalidationDelay: 300000, // 5 minutes
},
// Log detailed debugging messages, e.g. when items are cached or returned
// from cache.
debug: true,
// Disable logging a cache overview when the app starts.
disableCacheOverviewLogMessage: true,
// Allow overriding the current time with the
// x-nuxt-multi-cache-date-override request header (an ISO date string).
// Only use this in tests, see "Test Mode" below.
enableTestMode: process.env.E2E === 'true',
},
})Test Mode
With enableTestMode, any request can override the current time of the caches with the x-nuxt-multi-cache-date-override header. This makes it possible to test expiry and stale behavior in e2e tests.
DANGER
Never deploy a build with test mode enabled. Anyone could make cache items expire, or keep them cached far beyond their max age. The server logs a warning at startup if test mode is enabled.
Test mode is a build option, because e2e tests (for example with @nuxt/test-utils) run against a production build. Enable it only for the builds of your tests, for example with an environment variable as in the example above, or with Nuxt's $test override, which applies if NODE_ENV is test while the app is built:
typescript
export default defineNuxtConfig({
$test: {
multiCache: {
enableTestMode: true,
},
},
})Reference
ts
interface CacheConfigOptions {
/**
* Set if the cache is enabled.
*
* While the cache will be disabled during the app's runtime, all the
* corresponding code (components, composables, etc.) will still be added,
* even if the value is `false` here. This is so that it's possible to
* disable caching without having to refactor your code.
*
* If you wish to completely disable a feature so that no code is added just
* leave the entire configuration property undefined.
*/
enabled: boolean
}
export interface RouteCacheOptions extends CacheConfigOptions {
/**
* Add a Cache-Status header (RFC 9211) that says how the route cache
* handled the request, e.g. `nuxt-multi-cache; hit; ttl=376`.
*
* `true` uses the name `nuxt-multi-cache`, a string sets another name.
*
* Can be changed at runtime with `NUXT_MULTI_CACHE_ROUTE_CACHE_STATUS`.
*
* @default false
*/
cacheStatus?: boolean | string
/**
* The status codes of responses that the route cache stores.
*
* A stored response is served with its status code and headers, so adding
* redirect status codes (e.g. `[200, 301, 302, 307, 308]`) also caches
* redirects of `navigateTo()`. Make sure that the `Location` header only
* depends on what the cache key contains: by default the key is the path,
* without the query. Redirects to the same path (e.g. without the query or
* the trailing slash) are never stored, since their target would get the
* redirect from the cache.
*
* @default [200]
*/
statusCodes?: number[]
}
export type CDNOptions = {
/**
* Enable the CDN headers feature.
*/
enabled: boolean
/**
* The header to use for the cache-control settings.
*/
cacheControlHeader?: string
/**
* The header to use for the cache tags header.
*/
cacheTagHeader?: string
/**
* Add `private` to the Cache-Control header if the CDN header is marked as
* `private` or `no-store`.
*
* Not every CDN honors these directives in its own header: Fastly, for
* example, ignores them in Surrogate-Control and only skips caching for
* `Cache-Control: private`. An existing Cache-Control header is merged:
* `public` is removed, all other directives are kept.
*
* Disable this only if you make sure yourself that private responses are not
* cached by your CDN.
*
* @default true
*/
privateCacheControl?: boolean
}
export interface ModuleOptions {
/**
* Component cache.
*
* When enabled you can use the <RenderCacheable> wrapper component to cache
* the generated markup of its slot children. Each subsequent request will
* load the markup from cache and bypass rendering entirely.
*
* This is generally used for global components like navigation or footer.
* It also supports caching payloads.
*
* The performance improvements are most noticeable if you have complex
* components and a lot of pages.
*/
component?: CacheConfigOptions
/**
* Generic data cache.
*
* Can be used for anything: Caching API responses, expensive calculations,
* slow external APIs, etc.
*/
data?: CacheConfigOptions
/**
* Route cache.
*
* Caches routes based on the path. Works for both rendered Nuxt pages and
* server API routes.
*/
route?: RouteCacheOptions
/**
* Configuration for the CDN headers feature.
*
* This feature allows you to manage special HTTP headers used by
* Cloudflare, Fastly, Varnish and other caching services. These headers
* control how long a page should be cached, how long stale cache entries
* should be served, what the cache tags are, etc.
*
* Note that this is fundamentally different to the route cache: This
* feature only sets response headers, while the route cache actually caches
* pages.
*
* In addition, these headers are never sent to the client. They are
* intercepted by the CDN/HTTP cache and only used internally.
*
* It's possible to use both the CDN feature and the route cache at the same
* time. Note that they each have independent state; e.g. if you set a max
* age for the route cache it doesn't affect the max age value for the CDN
* headers.
*/
cdn?: CDNOptions
/**
* Settings for the API endpoints.
*/
api?: {
/**
* Enable the API endpoints for cache management.
*/
enabled?: boolean
/**
* The prefix used for the API endpoints.
*
* @default '/__nuxt_multi_cache'
*/
prefix?: string
/**
* The authorization for the API endpoints.
*
* If a string is provided, the auth check will be done using the
* `x-nuxt-multi-cache-token` header.
*
* If `false` is provided then authorization check is skipped. Only do
* this if you made sure that the API endpoints are not public, since this
* can potentially leak sensitive information via cached data or allow
* anyone to purge cache entries! A token set via runtime config is still
* required.
*
* If not provided, the token from runtime config is used, or else the
* `api.authorization` callback from the server options. If neither is
* set, the API endpoints respond with an error.
*/
authorization?: string | false
/**
* Delay for invalidating cache tags.
*
* Since purging by cache tag requires looping over all cache entries this
* action is debounced. The value (in milliseconds) will be the amount of
* delay that is used to buffer incoming tag invalidations. The delay is
* fixed and starts when the first invalidation request comes in, then all
* requests are added to the buffer. Once the delay is over, the cache
* entries for all the tags are purged and the timeout is reset.
*
* Set it to 0 to purge during the request: The API responds once the
* items are removed.
*
* For Cloudflare presets the delay is always 0, because Workers don't run
* timers after the response has been sent.
*
* @default 60000
*/
cacheTagInvalidationDelay?: number
}
/**
* Log detailled messages to the console.
*/
debug?: boolean
/**
* Don't log the caching overview.
*/
disableCacheOverviewLogMessage?: boolean
/**
* Enables test mode.
*
* The following is possible during test mode:
* - Current time override
* Send the X-Nuxt-Multi-Cache-Date-Override HTTP header to override the
* "current time" for anything nuxt-multi-cache related. This allows
* you to write tests for cache-related behaviour.
* The date should be in the ISO format returned by date.toISOString().
*
* Never deploy a build with test mode enabled: Any request could make cache
* items expire or keep them cached far beyond their max age. The server
* logs a warning at startup if it's enabled.
*/
enableTestMode?: boolean
}