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. 😄

[jayblast-spec]

[Svish]

I've so far found it best to keep them as JS, but with modern ES imports and proper usage of Jsdoc so everything is typed. The main remaining annoyance is any shared code you import into these cache handlers also need to be JS, which kind of sucks when it's code you want to share with the rest of the application as well, but it's not too bad.

I do wish it could at some point be possible to use just plain TS though, now that Node in theory should be able to run it directly with type erasure.

[js713-lab]

Tip for cacheHandlers + TypeScript

cacheHandlers is still evolving; typings sometimes lag the runtime.

Practical checklist:

1. Match your Next.js version docs for the exact cacheHandlers shape.
2. Put the file where Next expects it (often a root cache-handler module referenced from next.config).
3. Use module.exports / export default consistently with how next.config loads it (CJS vs ESM).
4. If TS complains about modern syntax in the handler file, compile that file separately or write it in plain CJS that Next can require.
5. After changes, delete .next and restart — handlers are easy to cache stale.

If you paste your next.config snippet and the TS error, we can pin the exact export shape.

[wesomitsu]

Yes, the Node type-stripping route works, and you don't need a compile step. Next.js doesn't bundle cache handlers. It loads the path from cacheHandlers at runtime with a plain import(), so Node's built-in type stripping (on by default since Node 22.18 / 23.6) runs a .ts file directly.

I tested this with Next 16.4.2 on Node 22.22. It worked with next dev, next build + next start, next build --webpack and output: 'standalone'. The handler and a shared .ts helper it imports both ran untranspiled:

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
  cacheHandlers: {
    default: require.resolve('./cache-handlers/memory-handler.ts'),
    // import.meta.resolve('./cache-handlers/memory-handler.ts') also works
  },
}

export default nextConfig

// cache-handlers/memory-handler.ts
import type { CacheEntry, CacheHandler } from 'next/cache'
import { log } from '../lib/log.ts' // shared TS code works too

type StoredEntry = Omit<CacheEntry, 'value'> & { value: Uint8Array }

const cache = new Map<string, StoredEntry>()
const pending = new Map<string, Promise<void>>()

const handler: CacheHandler = {
  async get(cacheKey) {
    await pending.get(cacheKey)
    const entry = cache.get(cacheKey)
    log(entry ? 'HIT' : 'MISS', cacheKey)
    if (!entry) return undefined
    return {
      ...entry,
      value: new ReadableStream<Uint8Array>({
        start(controller) {
          controller.enqueue(entry.value)
          controller.close()
        },
      }),
    }
  },
  async set(cacheKey, pendingEntry) {
    const { promise, resolve } = Promise.withResolvers<void>()
    pending.set(cacheKey, promise)
    try {
      const entry = await pendingEntry
      const value = new Uint8Array(await new Response(entry.value).arrayBuffer())
      cache.set(cacheKey, { ...entry, value })
    } finally {
      resolve()
      pending.delete(cacheKey)
    }
  },
  async refreshTags() {},
  async getExpiration() {
    return 0
  },
  async updateTags() {},
}

export default handler

Node strips the types but never reads tsconfig.json. That means the handler, and anything it imports, has to follow a few rules. These rules also mean shared code no longer has to be JS:

• Erasable syntax only: no enum, namespace or constructor parameter properties. An enum fails the build with ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX: TypeScript enum is not supported in strip-only mode. Add "erasableSyntaxOnly": true to tsconfig so Next's type-check catches it first (TS1294).
• Relative imports need the real extension: '../lib/log.ts', not '../lib/log'. Without the extension you get ERR_MODULE_NOT_FOUND. You also need "allowImportingTsExtensions": true, otherwise Next's type-check fails with TS5097. That option is allowed because Next already uses noEmit.
• No tsconfig paths aliases (@/lib/...) in the handler or in anything it imports. Use relative imports or package.json subpath imports ("#lib/*": "./lib/*" worked for me).
• Use import type for type-only imports.
• Add "type": "module" to package.json, or name the files .mts. Otherwise Node prints a MODULE_TYPELESS_PACKAGE_JSON warning for every .ts file with ESM syntax. It still works, but Node parses each file twice. require.resolve in next.config.ts kept working with "type": "module", because Next compiles that file itself.
• CacheHandler / CacheEntry are exported from next/cache starting with 16.4.0. On 16.3 and earlier, import them from next/dist/server/lib/cache-handlers/types.

With output: 'standalone', both .ts files were traced into .next/standalone, and node server.js loaded them fine. I only tested self-hosting, not Vercel. On Node 20 you'd still need the compile step.

Docs: cacheHandlers · Node.js type stripping

[wahyuarizeina]

Yes, there are two working approaches. Which one to use depends on your Node.js version.

Option 1: No build step (Next.js 16.4+, Node 22.18+ or 23.6+)

cacheHandlers loads the handler path with a plain runtime import(). Node's built-in type stripping can therefore run a .ts file directly, so no compile step is needed. The handler and any shared .ts code it imports run as-is.

Tested with Next.js 16.4.2 on Node 22.22, using next dev, next build + next start, next build --webpack, and output: 'standalone'.

next.config.ts

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
  cacheHandlers: {
    default: require.resolve('./cache-handlers/memory-handler.ts'),
    // import.meta.resolve('./cache-handlers/memory-handler.ts') also works
  },
}

export default nextConfig

cache-handlers/memory-handler.ts

import type { CacheEntry, CacheHandler } from 'next/cache'
import { log } from '../lib/log.ts'

type StoredEntry = Omit<CacheEntry, 'value'> & { value: Uint8Array }

const cache = new Map<string, StoredEntry>()
const pending = new Map<string, Promise<void>>()

const handler: CacheHandler = {
  async get(cacheKey) {
    await pending.get(cacheKey)
    const entry = cache.get(cacheKey)
    log(entry ? 'HIT' : 'MISS', cacheKey)
    if (!entry) return undefined
    return {
      ...entry,
      value: new ReadableStream<Uint8Array>({
        start(controller) {
          controller.enqueue(entry.value)
          controller.close()
        },
      }),
    }
  },
  async set(cacheKey, pendingEntry) {
    const { promise, resolve } = Promise.withResolvers<void>()
    pending.set(cacheKey, promise)
    try {
      const entry = await pendingEntry
      const value = new Uint8Array(await new Response(entry.value).arrayBuffer())
      cache.set(cacheKey, { ...entry, value })
    } finally {
      resolve()
      pending.delete(cacheKey)
    }
  },
  async refreshTags() {},
  async getExpiration() {
    return 0
  },
  async updateTags() {},
}

export default handler

lib/log.ts (shared code, also untranspiled)

export function log(status: 'HIT' | 'MISS', key: string) {
  console.log(`[cache] ${status} ${key}`)
}

tsconfig.json (relevant options)

{
  "compilerOptions": {
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "noEmit": true
  }
}

Rules for files loaded this way:

• Erasable syntax only. Do not use enum, namespace, or constructor parameter properties. Node fails with ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX. erasableSyntaxOnly makes TypeScript catch this first.
• Relative imports must include the .ts extension, for example '../lib/log.ts'. Without it you get ERR_MODULE_NOT_FOUND.
• No paths aliases (such as @/lib/...) in the handler or anything it imports. Use relative imports or package.json subpath imports (for example "#lib/*": "./lib/*").
• Use import type for type-only imports.
• Set "type": "module" in package.json, or name the files .mts. Otherwise Node prints a MODULE_TYPELESS_PACKAGE_JSON warning for each file. It still works, but Node parses each file twice.
• CacheHandler and CacheEntry are exported from next/cache starting with 16.4.0. On 16.3 and earlier, import them from next/dist/server/lib/cache-handlers/types instead.

Option 2: Compile step (older Node versions)

If you can't use Node type stripping, compile the handler to .mjs before dev and build. Thanks to @kanuwrld for this approach.

cache-handlers/remote-handler.mts

import type { CacheEntry, CacheHandler } from 'next/cache'

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

tsconfig.cache-handlers.json

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2022",
    "outDir": "cache-handlers/dist",
    "rootDir": "cache-handlers",
    "skipLibCheck": true
  },
  "include": ["cache-handlers/**/*.mts"]
}

package.json (scripts)

{
  "scripts": {
    "build:cache-handlers": "tsc -p tsconfig.cache-handlers.json",
    "predev": "npm run build:cache-handlers",
    "prebuild": "npm run build:cache-handlers"
  }
}

next.config.mjs

import { fileURLToPath } from 'node:url'

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

Note: next/cache types may not be exported on older Next.js versions. If the import fails, use next/dist/server/lib/cache-handlers/types, which is an internal path and may change between versions.

Summary

• Next.js 16.4+ on Node 22.18+ / 23.6+: use Option 1. No build step is needed.
• Older versions: use Option 2.
• The CommonJS examples in the docs reflect a documentation limitation, not an ESM runtime limitation. Updating the docs examples to ESM with JSDoc types would make this clearer for others.

[codeitwithaayush]

Yes, you can. The CJS-only examples are a docs limitation, not a runtime one.

• ESM works. Next loads handlers with a plain dynamic import() and unwraps the default export, so export default handler in a .mjs file is fine. No require.resolve needed. In next.config.mjs:

  import { fileURLToPath } from 'node:url'

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

• TypeScript works without a compile step on Node ≥ 22.18 / 23.6. Next doesn't bundle or transpile handler files, so Node's built-in type stripping runs the .ts file directly (see @wesomitsu's comment above for a tested setup).
• Types: CacheHandler and CacheEntry are exported from next/cache (16.4+).

Since Node only strips types and never reads tsconfig.json, the handler and everything it imports must:

• use erasable syntax only (no enum, namespace, constructor parameter properties). "erasableSyntaxOnly": true catches this early.
• use real extensions in relative imports ('../lib/log.ts'), with "allowImportingTsExtensions": true.
• avoid paths aliases. Use relative imports or package.json subpath imports (#lib/*).
• use import type for type-only imports.
• live in a package with "type": "module" (or use .mts) to avoid the MODULE_TYPELESS_PACKAGE_JSON warning.

On Node 20 or older, compile the handler to .mjs first (NodeNext), or use plain ESM .js with JSDoc types for editor typing with zero setup.

@icyJoseph @devjiwonchoi it would be great if the docs added an ESM/TS example (even as a tab next to the CJS one) and noted the Node version requirement. Happy to open a PR if that's welcome.