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.

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.
• last-modified -- Set to the current time when the response is first cached, if not already set.
• cache-control -- Automatically set based on the swr, maxAge, and staleMaxAge options, unless the handler already set one:
  • With swr: false (default): max-age=<maxAge>
  • With swr: true: s-maxage=<maxAge>, stale-while-revalidate=<staleMaxAge> (a bare stale-while-revalidate when staleMaxAge is unset)
• x-cache -- A CDN-style cache status header (HIT, STALE, REVALIDATED or MISS). Customizable with the cacheStatusHeader option.

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 or if-modified-since headers matching the cached response, Nitro returns a 304 Not Modified response without a body.

Request method filtering

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

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.

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 key like cache:nitro/functions:ghStars:<owner>/<repo>.json, 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`

For example, the following function:

import { defineCachedFunction } from "nitro/cache";

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

Will generate the following cache key:

cache:nitro/functions:getAccessToken:default.json

The default base is /cache, which the storage layer normalizes to the cache: prefix.

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 (and every handler created with defineCachedHandler) 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. For cached handlers, pass the event (e.g. .invalidate(event)).

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.

Standalone helpers

The invalidateCache(), expireCache(), and resolveCacheKeys() helpers work from the cache options used to define a cached function, so invalidation can live anywhere in your app, independent of where the cached function is defined.

Pass the same name, group, base, and getKey used when defining the function, along with the args identifying the entry:

import { invalidateCache } from "ocache";

await invalidateCache({
  options: {
    name: "ghStars",
    group: "nitro/functions",
    getKey: (repo: string) => repo,
  },
  args: ["unjs/nitro"],
});

expireCache() accepts the same input and marks the entry as stale instead of removing it, while resolveCacheKeys() returns the storage keys so you can operate on them directly.

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

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. When set to true, SWR is enabled with the default maxAge. When set to a number, it is used as the maxAge value in seconds.

import { defineConfig } from "nitro";

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

To explicitly disable caching on a route, set cache: false:

import { defineConfig } from "nitro";

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