Cache Middleware

The Cache middleware uses the Web Standards' Cache API.

The Cache middleware currently supports Cloudflare Workers projects using custom domains and Deno projects using Deno 1.26+. Also available with Deno Deploy.

Cloudflare Workers respects the Cache-Control header and return cached responses. For details, refer to Cache on Cloudflare Docs. Deno does not respect headers, so if you need to update the cache, you will need to implement your own mechanism.

See Usage below for instructions on each platform.

Import

import { Hono } from 'hono'
import { cache } from 'hono/cache'

Usage

Cloudflare Workers

app.get(
  '*',
  cache({
    cacheName: 'my-app',
    cacheControl: 'max-age=3600',
  })
)

Deno

// Must use `wait: true` for the Deno runtime
app.get(
  '*',
  cache({
    cacheName: 'my-app',
    cacheControl: 'max-age=3600',
    wait: true,
  })
)

Caching QUERY requests

The Cache middleware also caches responses to QUERY requests. As required by RFC 10008, the cache key for a QUERY request incorporates a digest of the request content and its representation metadata, so requests with different bodies are cached separately.

QUERY requests with a body larger than maxQueryBodySize (64 KiB by default) bypass the cache.

INFO

To support this, cached entries are stored under an internal key of the form /.hono/cache?__hono_cache_key=... instead of the request URL itself. If you purge cache entries directly through the Cache API — for example, calling caches.delete() with the original request URL — you will need to update that logic. This applies to all methods, including GET.

Options

required cacheName: string | (c: Context) => string | Promise<string>

The name of the cache. Can be used to store multiple caches with different identifiers.

optional wait: boolean

A boolean indicating if Hono should wait for the Promise of the cache.put function to resolve before continuing with the request. Required to be true for the Deno environment. The default is false.

optional cacheControl: string

A string of directives for the Cache-Control header. See the MDN docs for more information. When this option is not provided, no Cache-Control header is added to requests.

optional vary: string | string[]

Sets the Vary header in the response. If the original response header already contains a Vary header, the values are merged, removing any duplicates. Setting this to * will result in an error. For more details on the Vary header and its implications for caching strategies, refer to the MDN docs.

optional keyGenerator: (c: Context) => string | Promise<string>

Generates keys for every request in the cacheName store. This can be used to cache data based on request parameters or context parameters. The default is c.req.url. For QUERY requests, the key additionally includes a digest of the request content and its representation metadata.

optional maxQueryBodySize: number

The maximum QUERY request body size in bytes that can be cached. QUERY requests with a larger body bypass the cache. The default is 65536 (64 KiB).

optional cacheableStatusCodes: number[]

An array of status codes that should be cached. The default is [200]. Use this option to cache responses with specific status codes.

app.get(
  '*',
  cache({
    cacheName: 'my-app',
    cacheControl: 'max-age=3600',
    cacheableStatusCodes: [200, 404, 412],
  })
)

optional onCacheNotAvailable: ((reason: string) => void | Promise<void>) | false

A callback function or false that controls the behavior when the Cache API is not available in the global scope, or when QUERY caching cannot use Web Crypto. The callback is invoked with the reason. By default, the reason is logged with console.log. You can provide a custom function to customize the behavior, or set it to false to suppress the log entirely.

// Custom logging
app.use(
  cache({
    cacheName: 'my-app-v1',
    onCacheNotAvailable: () => {
      console.log('Custom log: Cache API is not available.')
    },
  })
)

// Suppress logging
app.use(
  cache({
    cacheName: 'my-app-v1',
    onCacheNotAvailable: false,
  })
)