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:

export default defineNuxtConfig({
  modules: ['nuxt-multi-cache'],

  multiCache: {
    data: {
      enabled: true,
    },
  },
})

This will still add all composables, but disable actual caching:

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:

export default defineNuxtConfig({
  modules: ['nuxt-multi-cache'],

  multiCache: {},
})

Full example

This example uses every possible configuration option.

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,
    },

    // CDN Cache Control Headers feature.
    cdn: {
      enabled: true,

      // Set custom cache control for Cloudflare.
      cacheControlHeader: 'CDN-Cache-Control',

      // Set custom cache tags header for Cloudflare.
      cacheTagHeader: 'Cache-Tag',
    },

    // Cache Management API.
    api: {
      enabled: true,

      // Use a different prefix for the API endpoints.
      prefix: '/api/nuxt-multi-cache',

      // Disable authorization check on the API.
      authorization: false,

      // Cache tag invaldiations should be buffered for 5 minutes before the
      // cache items are actually purged.
      cacheTagInvalidationDelay: 300000, // 5 minutes
    },

    // Log detailled 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,
  },
})

Reference

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 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
}

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,
   * but it can also be used to cache an entire page when used in a layout
   * component. 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?: CacheConfigOptions

  /**
   * 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!
     */
    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.
     */
    cacheTagInvalidationDelay?: number
  }

  /**
   * Log detailled messages to the console.
   */
  debug?: boolean

  /**
   * Don't log the caching overview.
   */
  disableCacheOverviewLogMessage?: boolean
}