Add Next.js 16.2.x compatibility patches (perf_hooks shim, fast-set-immediate shim, Turbopack handler delegation)

[chanceaclark]

What

Three build-time patches that make Next.js 16.2.x apps work on Cloudflare Workers. Without these, every app-router request crashes on cold start.

1. perf_hooks shim (f61f7c4)

Next 16.2.x bundles gc-observer.js (imports PerformanceObserver from perf_hooks) and @vercel/otel (uses require("perf_hooks").performance) into the instrumentation hook loading path. esbuild normalizes bare perf_hooks to node:perf_hooks on the node platform, and Workers does not expose this module even with nodejs_compat.

A new shim re-exports globalThis.performance and provides a no-op PerformanceObserver. Resolved via a new shimNodeModules onResolve plugin (not alias) so the shim is bundled instead of being externalized by platform: "node".

2. fast-set-immediate shim (b42ef6d)

Next 16.2's app-render-scheduling imports next/dist/server/node-environment-extensions/fast-set-immediate.external, whose top-level install() runs:

const nodeTimers = require('node:timers');
globalThis.setImmediate = nodeTimers.setImmediate = patchedSetImmediate;

Under nodejs_compat the node:timers namespace is a frozen ESM module, so nodeTimers.setImmediate = ... throws Cannot assign to read only property 'setImmediate' of object '[object Module]' on every request, before any user code runs.

The fast-immediate scheduler is an optimization, not a correctness requirement. A new shim exports the same names (DANGEROUSLY_runPendingImmediatesAfterCurrentTask, expectNoPendingImmediates, unpatchedSetImmediate) as no-ops and surfaces globalThis.setImmediate directly.

This commit also extends the bundle banner to expose AsyncLocalStorage on globalThis so Next's async-local-storage.js picks up the real implementation rather than falling back to FakeAsyncLocalStorage (which throws on .run()/.exit() and cascades into a confusing Cannot read properties of undefined (reading 'require') when Turbopack loads app-page-turbo.runtime.prod.js).

3. patchPageExports plugin (39ab69b)

Next 16.2.x Turbopack app-page templates set up exports on a child module via esmExport(bindings, childId), then re-call esmExport for the entry module's own id. Each page chunk then does:

R.m(<entryId>)
module.exports = R.m(<entryId>).exports

R.m(<entryId>).exports only carries the second call's vendored bindings — handler lives on the child module. At request time Next reads components.ComponentMod.handler, gets undefined, and crashes with ComponentMod.handler is not a function on every app route.

The fix:

1. Scan SSR app-page template chunks under .next/server/chunks/ssr/ to build an entry→child module-id map by anchoring on module.exports = [<entryId> and a.s([…,"handler",…], <childId>).
2. Add an esbuild onLoad plugin that matches .next/server/app/**/page.js and .next/server/app/**/route.js. When the entry id has a recorded child, replace the terminator with a merge expression that copies the entry's own-property descriptors first, then layers the child's descriptors for keys the entry doesn't define. The merged object exposes handler alongside the Turbopack bindings while preserving lazy getters.

The patch only touches page.js / route.js. It does not modify the Turbopack runtime, esmExport, or instantiateModule, so it cannot regress instrumentation hook loading or app-page-turbo external loading.

Why

Without these three patches, Next.js 16.2.x on Cloudflare Workers fails on every request:

• Cold start crashes at gc-observer.js evaluation (perf_hooks)
• First request crashes at fast-set-immediate's install() (node:timers mutation)
• Every app-router request crashes at ComponentMod.handler is not a function

Together they make a real Next 16.2.6 app-router storefront return 200s across homepage, search, category, product, brand, and blog routes.

Testing

Verified locally with a Next.js 16.2.6 app-router site running under [email protected] dev. Without the patches: 500 on every request. With the patches: 200 across the homepage, search, compare, category, product, brand, and blog routes.

tsc --noEmit and eslint are clean.

Notes

• Related to [BUG] Next 16.2.5 / 16.2.6 + 1.19.8 — every dynamic route 500s with ComponentMod.handler is not a function (and a leading-slash dynamic require of /.next/server/middleware-manifest.json) #1258.
• One changeset (patch) covers all three fixes.
• Happy to split into three separate PRs if that's preferable for review.

[changeset-bot]

🦋 Changeset detected

Latest commit: 17ee18e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@opennextjs/cloudflare	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 5 additional findings.

[vicb]

Thanks for the PR @chanceaclark

• Happy to split into three separate PRs if that's preferable for review.

That would really be helpful please - please include a repro of the failure (link to a GH repo with instruction) for each of them.

Some comments/thoughts about your points above:

1. perf_hooks

esbuild normalizes bare perf_hooks to node:perf_hooks on the node platform, and Workers does not expose this module even with nodejs_compat

perf_hooks is implemented natively in workerd if the compatibility date is on or after 2026-03-17

2. Cannot assign to read only property 'setImmediate' of object '[object Module]'

There used to be a bug in workerd. It has been fixed months ago. Here again a recent compatibility date might be enough to fix the issue.

So before splitting this PR into multiple issues, it would be nice to try and bump the compatibility_date to something recent i.e. 2026-04-15 and check if it is enough to fix at least 1 and 2.

We have recently added a build time warning for older compat date. We should probably turn this into a build error.

This might also explain why I was not able to repro #1258.

[chanceaclark]

1. and 2. were resolved by bumping the compatibility date like you said 👨‍🍳 💋

I could only reproduce 3. on older versions of wrangler, I assume maybe it's because of previous module resolution bundling happening 🤷‍♂️ Didn't dig too deep, but upgrading wrangler to the latest solved it.

Closing this PR.