Workers: Node.js compat flags and compatibility_date, done right

Node.js compatibility on Workers, without the guessing

Workers run on workerd (V8 isolates), not Node.js. Many npm packages import Node builtins (node:fs, node:crypto, Buffer, process). Whether those resolve is controlled by compatibility flags, and getting this wrong is the most common reason a deploy builds fine and crashes at runtime.

The date rule (current as of the docs, updated Aug 2026)

• compatibility_date of 2026-08-04 or later: nodejs_compat and nodejs_compat_v2 are enabled by default. Built-in Node.js APIs and polyfills work with no extra config. Do not add the flags to new configs.
• 2024-09-23 through 2026-08-03: add "nodejs_compat" to compatibility_flags to opt in.
• Older than that: Node APIs are largely unavailable; upgrade the date before debugging the package.

{
  "compatibility_date": "2026-08-03",
  "compatibility_flags": ["nodejs_compat"]
}

What the flags actually give you

Two forms: real built-in implementations of Node APIs in the runtime, and polyfill shims Wrangler adds at build time. The shims let a module import without failing, but calling a shimmed method throws at runtime. So "it bundled" is not proof "it runs". Test the actual code path.

Turning it off completely

For a date of 2026-08-04 or later, add both no_nodejs_compat and no_nodejs_compat_v2 (and remove any positive flags). Do this only if you want the pure workerd surface.

Checklist

• New project: set compatibility_date to today, skip the flags entirely.
• Migrating an old Worker: bump the date in a preview first, run your full request paths, then promote.
• If a dependency fails with a Node builtin error after the flag is set, the package is likely calling a shimmed API; check the supported-API list on the docs page before patching around it.

Verified against the live Node.js compatibility doc (updated Aug 12, 2026): 2026-08-04 enables both flags by default, flag form for 2024-09-23 to 2026-08-03, opt-out via nonodejscompat + nonodejscompat_v2, shim vs built-in distinction. Ref: https://developers.cloudflare.com/workers/runtime-apis/nodejs/