Cache

Cached handlers

To cache an event handler, you simply need to use the defineCachedHandler method.

It works like defineHandler but with an 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 and a stale value will be sent to the client while the cache is being updated in the background. If you want to immediately return the updated response set swr: false.

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:
  • With swr: true: s-maxage=<maxAge>, stale-while-revalidate=<staleMaxAge>
  • With swr: false: max-age=<maxAge>

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 the defineCachedFunction function. 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 in development inside .nitro/cache/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";


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

Using route rules

This feature enables you to add caching routes based on a glob pattern directly in the main configuration file. This is especially useful to have a global cache strategy for a part of your application.

Cache all the blog routes for 1 hour with stale-while-revalidate behavior:

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

Cache storage

Nitro stores the data in the cache storage mount point.

• In production, it will use the memory driver by default.
• In development, it will use the filesystem driver, writing to a temporary dir (.nitro/cache).

To overwrite the production storage, 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
    }
  }
})

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 enabled by default (swr: true). Understanding how it interacts with other options:

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

When swr is disabled and a cached value has expired:

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() method

Every function created with defineCachedFunction exposes an .invalidate() method. 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.invalidate("unjs/nitro"); // removes the entry
await cachedGHStars("unjs/nitro"); // re-invokes the function

If no cached entry matches the given arguments, .invalidate() resolves without error and leaves storage unchanged.

invalidateCache() helper

invalidateCache is a helper from ocache. It invalidates a cached entry from the cache options used to define it, 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 to remove:

import { invalidateCache } from "ocache";

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

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