cacheHandlers doesn't support Typescript or modern module syntax?

[Svish]

Summary

All the examples of custom cacheHandlers on https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheHandlers seem to be written as awful, old school CommonJS stuff. The configuration refers to them via require.resolve, the file itself is .js, and it uses module.exports and require.

We're in 2026, can I really not write a custom cache handler for Next in Typescript using ESM?

Additional information

No response

Example

No response

[icyJoseph]

I had drafted this a while ago: https://github.com/vercel/next.js/pull/89933/changes — which is not ideal, more of a workaround. Let me check with a colleague who might have more input.

[Svish]

That's definitely a workaround, yes, but the reasoning makes sense.

Now that Node supports Typescript out of the box via type-erasure, could it be possible without a workaround now, as long as the version of Node supports that? If yes, it would be great if an example of that was added to the docs, maybe even made the "default" example.

[icyJoseph]

cc @devjiwonchoi — to update this thread with our findings/proposal

[kanuwrld]

Current behavior is:

• ESM handler: yes
• raw TypeScript handler: no; compile it first

The handler loader already uses dynamic import() and unwraps a default export, so a .mjs file with export default is supported. The relevant path is loadCustomCacheHandlers(), backed by the ESM/CJS interop loader at lines 139–142.

What Next does not do is run handler files through the next.config.ts transpilation path. Config validation resolves the supplied handler path and checks that it exists; the production server later imports that exact file. So .ts/.mts source should produce JavaScript before next dev or next build.

A modern ESM setup can look like this:

// cache-handlers/remote-handler.mts
import type {
  CacheEntry,
  CacheHandler,
} from "next/dist/server/lib/cache-handlers/types"

const cache = new Map<string, CacheEntry>()

const handler: CacheHandler = {
  async get(key) {
    return cache.get(key)
  },
  async set(key, pendingEntry) {
    cache.set(key, await pendingEntry)
  },
  async refreshTags() {},
  async getExpiration() {
    return 0
  },
  async updateTags() {},
}

export default handler

Compile .mts with module/moduleResolution set to NodeNext; TypeScript emits .mjs. Then point an ESM config at the emitted file without require.resolve:

// next.config.mjs
import { fileURLToPath } from "node:url"

export default {
  cacheHandlers: {
    remote: fileURLToPath(
      new URL("./cache-handlers/dist/remote-handler.mjs", import.meta.url),
    ),
  },
}

Run the handler compile step from predev and prebuild, so both commands see the emitted file.

One caveat: next/dist/server/lib/cache-handlers/types is currently an internal type path, not a stable public export. It is also the type used in the draft documentation change in #89933, but I would keep the import isolated because that path can change between Next versions.

So the CommonJS examples are a documentation limitation, not an ESM runtime limitation. Direct TypeScript loading is the unsupported part.

[Svish]

That makes sense. Gotta say it seems like a bit of hassle to write it in TS then, but great if it can be documented how it could be done. I think it would help a lot if the documentation and examples were just updated to ESM with JSDoc types. That way you could still run them without extra setup, but you'd also get editor information about types which helps a lot when trying to understand APIs and how things work. 😄