Skip to content

Cache Management API ​

This feature provides several API endpoints to manage the caches. You can get a list of cache items, inspect cache items, delete items by key or delete items by cache tags.

Configuration ​

typescript
export default defineNuxtConfig({
  multiCache: {
    api: {
      enabled: true,
      prefix: '/__nuxt_multi_cache',
      // Token based authorization. Leave it out to use the authorization
      // callback from the server options instead.
      authorization: 'hunter2',
      cacheTagInvalidationDelay: 60000,
    },
  },
})
typescript
import { defineMultiCacheOptions } from 'nuxt-multi-cache/server-options'
import { isAuthenticated } from './somewhere'

export default defineMultiCacheOptions(() => {
  return {
    api: {
      // Use a custom method that checks authorization. Can be something like
      // cookie, basic auth or request IP. Only used if no token is set.
      authorization: async function (event) {
        return await isAuthenticated(event)
      },
    },
  }
})

Authorization ​

By default the endpoints are not accessible without authorization.

Token based (x-nuxt-multi-cache-token) ​

This is the default authorization used when the api.authorization option is provided. In this case the token is expected in the x-nuxt-multi-cache-token header:

typescript
fetch('http://localhost:3000/__nuxt_multi_cache/purge/component', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-nuxt-multi-cache-token': 'hunter2', 
  },
  body: JSON.stringify(['Navbar::de--chf']),
})
bash
curl -X POST -i \
  -H "Content-Type: application/json" \
  -H "x-nuxt-multi-cache-token: hunter2" \
  --data '["Navbar::de--chf"]' \
  http://localhost:3000/__nuxt_multi_cache/purge/component

It's also possible to provide the token using runtime config:

dotenv
NUXT_MULTI_CACHE_API_AUTHORIZATION_TOKEN=PtSR0mDATQpNlvNgqRf

Custom Callback ​

You can also implement your own authorization check via the server options. In this case, leave out the api.authorization module option.

If no authorization is configured at all, the endpoints respond with a 500 error.

Disabled ​

You can disable authorization by setting the value of api.authorization to false. Only do this if the endpoints are not accessible publicly!

A token always takes precedence: If a token is set via runtime config, it is required, even if authorization is disabled. This way api.authorization: false can be used for local development, with a token provided for production.

Caching ​

The responses of the API are never cached: They are excluded from the route cache and sent with Cache-Control: private, no-store. If the CDN feature is enabled, the CDN header is also marked as private and no-store with a max age of 0, even if a middleware made every response public.

Purge Everything ​

Purges everything from all caches.

typescript
fetch('http://localhost:3000/__nuxt_multi_cache/purge/all', {
  method: 'POST',
  headers: {
    'x-nuxt-multi-cache-token': 'hunter2',
  },
})
bash
curl -X POST -i \
  -H "x-nuxt-multi-cache-token: hunter2" \
  http://localhost:3000/__nuxt_multi_cache/purge/all
Response
json
{
  "status": "OK"
}

Purge Item ​

Purge one or more cache items by key. The last part of the path is the name of the cache: component, data or route. If the cache is not enabled, the endpoint responds with a 404 status code.

The keys must be the keys as they are stored, including the global cache prefix if one is set. You can find them using Get Stats.

The affectedKeys in the response are the keys from the request, whether an item existed for them or not.

Example: Purge component with key Navbar::de--chf ​

typescript
fetch('http://localhost:3000/__nuxt_multi_cache/purge/component', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-nuxt-multi-cache-token': 'hunter2',
  },
  body: JSON.stringify(['Navbar::de--chf']),
})
bash
curl -X POST -i \
  -H "Content-Type: application/json" \
  -H "x-nuxt-multi-cache-token: hunter2" \
  --data '["Navbar::de--chf"]' \
  http://localhost:3000/__nuxt_multi_cache/purge/component
Response
json
{
  "status": "OK",
  "affectedKeys": ["Navbar::de--chf"]
}

Example: Purge two specific pages ​

typescript
fetch('http://localhost:3000/__nuxt_multi_cache/purge/route', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-nuxt-multi-cache-token': 'hunter2',
  },
  body: JSON.stringify(['/about', '/product/123']),
})
bash
curl -X POST -i \
  -H "Content-Type: application/json" \
  -H "x-nuxt-multi-cache-token: hunter2" \
  --data '["/about", "/product/123"]' \
  http://localhost:3000/__nuxt_multi_cache/purge/route
Response
json
{
  "status": "OK",
  "affectedKeys": ["/about", "/product/123"]
}

Purge Tags ​

Purge cache items by cache tags.

INFO

All tags are collected for some time (default: 1min), after which the cache items are purged. This is because cache tags are stored together with the items. Unless a cache tag registry is used, every item needs to be loaded from the cache and its tags checked.

The delay is configurable via the api.cacheTagInvalidationDelay option (in milliseconds). With a delay, the response only confirms that the tags were received, and errors while purging are logged on the server.

Set it to 0 to purge the items during the request, without collecting tags: The response is sent once the items are removed, and an error while removing them results in an error response.

For Cloudflare presets the delay is always 0, see Cloudflare Workers.

Example Purge all cache items with cache tag language:de ​

typescript
fetch('http://localhost:3000/__nuxt_multi_cache/purge/tags', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-nuxt-multi-cache-token': 'hunter2',
  },
  body: JSON.stringify(['language:de']),
})
bash
curl -X POST -i \
  -H "Content-Type: application/json" \
  -H "x-nuxt-multi-cache-token: hunter2" \
  --data '["language:de"]' \
  http://localhost:3000/__nuxt_multi_cache/purge/tags
Response
json
{
  "status": "OK",
  "tags": ["language:de"]
}

Get Stats ​

Get a list of all items in a cache.

Example: Get a list of all cached components ​

typescript
fetch('http://localhost:3000/__nuxt_multi_cache/stats/component', {
  headers: {
    'x-nuxt-multi-cache-token': 'hunter2',
  },
})
bash
curl -i \
  -H "x-nuxt-multi-cache-token: hunter2" \
  http://localhost:3000/__nuxt_multi_cache/stats/component
Response
json
{
  "status": "OK",
  "rows": [
    {
      "key": "Navbar::de--chf",
      "data": "{\"payload\":{},\"cacheTags\":[\"navbar\"],\"ssrModules\":[\"components/Navbar.vue\"],\"expires\":-1,\"staleIfErrorExpires\":0}<CACHE_ITEM><nav class=\"navbar\">...</nav>"
    }
  ],
  "total": 1
}

Items of the component and route cache are stored as a string: Their metadata as JSON, followed by <CACHE_ITEM> and the markup or response body. Items of the data cache are stored as objects.

Inspect ​

Inspect a cache item. The key should be provided as a query param key. If no item exists for the key, the endpoint responds with a 404 status code.

The item is returned as it is stored (see Get Stats). Route and component items are stored as strings and sent as plain text (text/plain), so that a browser doesn't render their content as HTML.

Example: Get the cached component with key Navbar::de--chf ​

typescript
fetch(
  'http://localhost:3000/__nuxt_multi_cache/inspect/component?key=Navbar::de--chf',
  {
    headers: {
      'x-nuxt-multi-cache-token': 'hunter2',
    },
  },
)
bash
curl -i \
  -H "x-nuxt-multi-cache-token: hunter2" \
  "http://localhost:3000/__nuxt_multi_cache/inspect/component?key=Navbar::de--chf"
Response
{"payload":{},"cacheTags":["navbar"],"ssrModules":["components/Navbar.vue"],"expires":-1,"staleIfErrorExpires":0}<CACHE_ITEM><nav class="navbar">...</nav>

Example: Get the details of a cached route ​

typescript
fetch('http://localhost:3000/__nuxt_multi_cache/inspect/route?key=api:test', {
  headers: {
    'x-nuxt-multi-cache-token': 'hunter2',
  },
})
bash
curl -i \
  -H "x-nuxt-multi-cache-token: hunter2" \
  "http://localhost:3000/__nuxt_multi_cache/inspect/route?key=api:test"
Response
{"headers":{"cache-tag":"page:1 language","surrogate-control":"max-age=3600, public","content-type":"application/json"},"statusCode":200,"expires":1793382047,"cacheTags":["page:1","language"],"staleIfErrorExpires":0,"staleWhileRevalidate":false}<CACHE_ITEM>{"api":"This is data from the API."}

Released under the MIT License.