Cache

Caching lets you store the result of expensive operations (rendered responses, upstream API calls, heavy computations) and serve it again without redoing the work. Nitro offers three ways in:

• Cached handlers: cache the full response of an event handler.
• Cached functions: cache the result of any function and reuse it across handlers.
• Route rules: enable caching for route patterns from your config, without touching handler code.

#Cached handlers

To cache an event handler, use the defineCachedHandler method.

It works like defineHandler but with a second parameter for the cache options.

import { defineCachedHandler } from "nitro/cache";

export default defineCachedHandler((event) => {
  return "I am cached for an hour";
}, { maxAge: 60 * 60 });

With this example, the response will be cached for 1 hour. Once the cache expires, the next request waits for the handler to resolve a fresh value before responding. If you prefer to immediately serve the stale response while it is revalidated in the background, set swr: true (see SWR behavior).

See the options section for more details about the available options.

#What the handler can see

For cacheable requests, a handler receives exactly the request data that the cache key covers. Everything else is removed before the handler runs, so a handler cannot render output from a value the key does not distinguish and have it stored under a shared key:

• Request headers are stripped unless listed in varies. This includes if-none-match / if-modified-since (Nitro answers conditional requests itself) and tracing headers such as traceparent or x-request-id.
• Query parameters are stripped unless listed in allowQuery. By default /page, /page?a=1 and /page?utm=x all share one entry, and url.searchParams is empty inside the handler.
• Cookies are stripped unless listed in allowCookies, and set-cookie is removed from every cached response.
• authorization / proxy-authorization are stripped unless allowAuthorization is set.
• host is the one header that is rewritten rather than removed: it carries the host of the resolved request origin, which is part of the key. A handler serving several hostnames therefore gets one entry per host.

Use shouldBypassCache for requests that must reach the handler untouched. A bypassed request keeps its headers, cookies, query string and body, and its response is returned without being stored.

#Automatic HTTP headers

When using defineCachedHandler, Nitro automatically manages HTTP cache headers on cached responses:

• etag: a weak ETag (W/"...") is generated from the response body hash if not already set by the handler.
• cache-control: synthesized from the lifetime actually enforced for the entry, unless the handler already set one (see the table below).
• vary: every name in varies is merged into the response Vary, plus Cookie when allowCookies is used. allowQuery adds nothing, because query parameters already live in the URL.
• x-cache: a CDN-style cache status header (HIT, STALE, REVALIDATED or MISS). Customizable with the cacheStatusHeader option.

stale-while-revalidate is only advertised when staleMaxAge is set, since the directive requires a number of seconds. With swr: true and no staleMaxAge the stale window is unlimited, so downstream caches simply revalidate after max-age while Nitro answers from its stale copy.

To keep caching server-side only without advertising cache-control to clients and CDNs, set sendCacheControl: false.

#Conditional requests (304 Not Modified)

Cached handlers automatically support conditional requests. When a client sends if-none-match matching the cached etag, or if-modified-since at or after a last-modified the handler set, Nitro returns a 304 Not Modified response without a body. if-none-match wins when both are present.

The request validators are captured before the request is narrowed, so the handler never sees them and cannot do its own conditional handling.

#Cacheable requests

Only GET and HEAD requests are cached. All other HTTP methods (POST, PUT, DELETE, etc.) automatically bypass the cache and call the handler directly, as do requests carrying a Range header.

GET and HEAD are cached under separate entries, since a HEAD response carries no body. The method stays part of the key even with a custom getKey.

#Request deduplication

When multiple concurrent requests hit the same cache key while the cache is being resolved, only one invocation of the handler runs. All concurrent requests wait for and share the same result.

A shared resolution is bounded by maxResolveTime (30 seconds by default). On timeout every waiter rejects with a TimeoutError, the entry being refreshed is evicted, and the key is free again. Handlers additionally receive that deadline as event.req.signal, so you can forward it to upstream fetch calls.

#Cached functions

You can also cache a function using defineCachedFunction. This is useful for caching the result of a function that is not an event handler, but is part of one, and reusing it in multiple handlers.

For example, you might want to cache the result of an API call for one hour:

import { defineCachedFunction } from "nitro/cache";
import { defineHandler, type H3Event } from "nitro";

export default defineHandler(async (event) => {
  const { repo } = event.context.params;
  const stars = await cachedGHStars(repo).catch(() => 0)

  return { repo, stars }
});

const cachedGHStars = defineCachedFunction(async (repo: string) => {
  const data = await fetch(`https://api.github.com/repos/${repo}`).then(res => res.json());

  return data.stargazers_count;
}, {
  maxAge: 60 * 60,
  name: "ghStars",
  getKey: (repo: string) => repo
});

The stars will be cached using the cache storage (in-memory by default) under a cache key derived from the group, name and getKey result, with value being the number of stars.

{"expires":1677851092249,"value":43991,"mtime":1677847492540,"integrity":"ZUHcsxCWEH"}

import { defineCachedFunction } from "nitro/cache";
import { defineHandler, type H3Event } from "nitro";

export default defineHandler(async (event) => {
  const { repo } = event.context.params;
  const stars = await cachedGHStars(event, repo).catch(() => 0)

  return { repo, stars }
});

const cachedGHStars = defineCachedFunction(async (event: H3Event, repo: string) => {
  const data = await fetch(`https://api.github.com/repos/${repo}`).then(res => res.json());

  return data.stargazers_count;
}, {
  maxAge: 60 * 60,
  name: "ghStars",
  getKey: (event: H3Event, repo: string) => repo
});

#Options

The defineCachedHandler and defineCachedFunction functions accept the following options:

#Shared options

These options are available for both defineCachedHandler and defineCachedFunction:

#Handler-only options

These options are only available for defineCachedHandler:

#Function-only options

These options are only available for defineCachedFunction:

#SWR behavior

The stale-while-revalidate (SWR) pattern is opt-in via the swr option (disabled by default). Understanding how it interacts with other options:

When swr is enabled and a cached value exists but has expired:

When swr is disabled (default) and a cached value has expired:

#Cache keys

When using the defineCachedFunction or defineCachedHandler functions, the cache key is generated using the following pattern:

`${options.base}:${options.group}:${options.name}:${options.getKey(...args)}.json`

group and name are escaped before they enter the key: characters outside [A-Za-z0-9_] are removed and, when that changed the value, a hash of the raw value is appended. That is why Nitro's nitro/functions group appears as nitrofunctions.<hash> and cannot be confused with the : key structure. The getKey result is the terminal segment and is stored exactly as returned.

For example, the following function:

import { defineCachedFunction } from "nitro/cache";

const getAccessToken = defineCachedFunction(() => {
  return String(Date.now())
}, {
  maxAge: 10,
  name: "getAccessToken",
  getKey: () => "default"
});

Will be stored under a key like:

cache:nitrofunctions.3aFYDY_G88ZLdElv-hEB0r8snSViMYJ1NbRtlNP9o_0:getAccessToken:default.json

The default base is /cache, which the storage layer normalizes to the cache: prefix (as it does with any other / in the key).

#What gets cached

Before a response is stored, the following checks apply. A response that fails any of them is still returned to the caller, it is just never stored or served from the cache:

These checks always apply. Use shouldCache to narrow further. A response rejected by a built-in check also gets no synthesized cache-control, so a CDN in front cannot hold on to an error; a response rejected by your shouldCache still does.

#Cache invalidation

Cached entries can be invalidated programmatically at runtime (for example from a webhook when the underlying data changes) without waiting for maxAge to expire.

#.invalidate() and .expire() methods

Every function created with defineCachedFunction exposes on-demand revalidation methods:

• .invalidate(...args): removes the cached entry entirely. The next call re-invokes the function and waits for the fresh value.
• .expire(...args): marks the cached entry as stale without removing it. With swr enabled, the stale value is still served while the next call triggers a background refresh; without SWR, the next call re-resolves before returning.
• .resolveKeys(...args): resolves the storage key(s) the entry is cached under (one per base prefix).

Arguments are passed through getKey to generate the cache key.

import { defineCachedFunction } from "nitro/cache";

const cachedGHStars = defineCachedFunction(async (repo: string) => {
  const data = await fetch(`https://api.github.com/repos/${repo}`).then(res => res.json());
  return data.stargazers_count;
}, {
  maxAge: 60 * 60,
  name: "ghStars",
  getKey: (repo: string) => repo,
});

await cachedGHStars("unjs/nitro"); // populates the cache
await cachedGHStars.expire("unjs/nitro"); // marks the entry as stale
await cachedGHStars.invalidate("unjs/nitro"); // removes the entry
await cachedGHStars("unjs/nitro"); // re-invokes the function

If no cached entry matches the given arguments, .invalidate() and .expire() resolve without error and leave storage unchanged. Both also cancel a resolution already in flight for that key, so a pre-purge value cannot be written after the purge.

#Cache storage

Cache entries are stored using the storage layer under the cache: prefix (derived from the default base: "/cache" option).

By default, no dedicated mount point is configured for it: entries live in the root storage, which uses an in-memory driver and is not persisted across restarts, in both development and production.

To use a persistent backend, set the cache mount point using the storage option:

import { defineConfig } from "nitro";

export default defineConfig({
  storage: {
    cache: {
      driver: 'redis',
      /* redis connector options */
    }
  }
})

In development, you can also overwrite the cache mount point using the devStorage option:

import { defineConfig } from "nitro";

export default defineConfig({
  storage: {
    cache: {
      // production cache storage
    },
  },
  devStorage: {
    cache: {
      // development cache storage
    }
  }
})

#Using route rules

Route rules let you enable caching for all routes matching a glob pattern, directly from your configuration. This is especially useful for a global cache strategy across a part of your application, without touching handler code.

Cache all the blog routes for 1 hour:

import { defineConfig } from "nitro";

export default defineConfig({
  routeRules: {
    "/blog/**": { cache: { maxAge: 60 * 60 } },
  },
});

The cache rule accepts the same handler options documented above (swr, staleMaxAge, varies, allowQuery, allowCookies, allowAuthorization, sendCacheControl, cacheStatusHeader, stream, maxBodySize, headersOnly, base, group, name, integrity, maxResolveTime). Hook options such as shouldCache are only available on defineCachedHandler.

If we want to use a custom cache storage mount point, we can use the base option.

import { defineConfig } from "nitro";

export default defineConfig({
  storage: {
    redis: {
      driver: "redis",
      url: "redis://localhost:6379",
    },
  },
  routeRules: {
    "/blog/**": { cache: { maxAge: 60 * 60, base: "redis" } },
  },
});

#Route rules shortcuts

You can use the swr shortcut for enabling stale-while-revalidate caching on route rules. swr: 3600 is shorthand for cache: { swr: true, maxAge: 3600 }. When set to true, SWR is enabled with the default maxAge of 1 second, so prefer passing an explicit number.

import { defineConfig } from "nitro";

export default defineConfig({
  routeRules: {
    "/blog/**": { swr: 3600 },
    "/api/**": { swr: 60 },
  },
});

To explicitly disable caching on a route, set cache: false (or swr: false) on a more specific pattern. This also removes a cache rule inherited from a broader pattern:

import { defineConfig } from "nitro";

export default defineConfig({
  routeRules: {
    "/api/**": { swr: 60 },
    "/api/realtime/**": { cache: false },
  },
});