skip to content

In Cloudflare Workers, what does nodejs_compat turn on, and how does the compatibility date decide whether a Worker has it?

level: middleimportance: must knowfreq 48%

answer

  1. native modules plus build polyfills
  2. node: prefix, then bare names
  3. Buffer and process globals
  4. default on from 2026-08-04
  5. two no_ flags to opt out

basics

~20 s

nodejs_compat lets a Worker import the Node.js built-ins workerd implements and, on newer dates, use Buffer and process globals plus Wrangler's unenv polyfills. It is on by default from compatibility date 2026-08-04; earlier dates opt in.

solid answer

~30 s

`nodejs_compat` exposes Node.js built-ins that workerd implements natively, such as `node:crypto`, `node:buffer` and `node:stream`. With a compatibility date before 2024-09-23 that is all (v1: `node:` imports only, no globals). From 2024-09-23 it brings v2: bare names like `crypto`, the `Buffer` and `process` globals, and unenv polyfills Wrangler bundles for modules the runtime lacks, whose unimplemented methods throw. From 2026-08-04 the date turns v2 on with no flag at all. Opting out on such a date takes both `no_nodejs_compat` and `no_nodejs_compat_v2`; one alone leaves v2 on. Later dates also switch on more modules under the same flag, such as `node:fs` from 2025-09-15.

code

json · 6 lines
json
{
  "name": "invoice-signer",
  "main": "src/index.js",
  "compatibility_date": "2026-08-03",
  "compatibility_flags": ["nodejs_compat"]
}

go deeper

for a junior

Recall that npm packages using Node.js built-ins need Node.js compatibility, and that Workers dated 2026-08-04 or later have it without any flag.

for a middle

Explain native built-ins versus unenv polyfills, the v1 and v2 modes by date, and why opting out takes both no_nodejs_compat and no_nodejs_compat_v2.

for a senior

Show you can tell a missing module from a polyfill that throws at call time, and know which date-gated module changes ride on the flag.

for a principal

Weigh the default-on Node.js surface and bundle size against package reach, and decide which Workers should opt out explicitly.

## Two ways Node.js APIs reach a Worker A Worker runs on workerd, a V8-based runtime built around web-standard APIs, not on Node.js. Many npm packages still import Node.js built-ins such as `node:crypto`, `node:buffer` or `node:stream`, or reach for the `Buffer` and `process` globals. **Node.js compatibility** is how Cloudflare makes those packages load, and it works in two layers: 1. **Native built-ins in the runtime.** workerd implements a growing list of Node.js modules itself: `buffer`, `crypto`, `stream`, `events`, `util`, `path`, `url`, `zlib`, `async_hooks` (AsyncLocalStorage), `net`, client-side `http` and `https`, a virtual-filesystem `fs`, `process` and more. These are real implementations. 2. **Build-time polyfills from Wrangler.** For what the runtime does not implement, Wrangler's bundler substitutes **unenv** shims. Importing such a module succeeds, but calling an unimplemented method either does nothing or throws `[unenv] <method> is not implemented yet!`. A third group, such as `node:child_process`, `node:worker_threads` and `node:cluster`, exists as **non-functional stubs**: importable so a package that checks for the module can load, with methods that throw (`The child_process.execSync method is not implemented`). A Worker never becomes a Node.js process. ## Which mode a Worker gets The compatibility date and flags select one of these modes: | Compatibility date | Configuration | Result | |---|---|---| | before 2026-08-04 | no flag | no Node.js modules: `No such module "node:crypto"` | | before 2024-09-23 | `nodejs_compat` | v1: native modules through `node:` imports only, no `Buffer` or `process` globals, no polyfills | | 2024-09-23 to 2026-08-03 | `nodejs_compat` | v2: `node:` and bare names (`crypto`), `Buffer` and `process` globals, unenv polyfills | | 2026-08-04 or later | nothing | v2 is on by default | | 2026-08-04 or later | `no_nodejs_compat` and `no_nodejs_compat_v2` | fully off | Before 2024-09-23 a team could also add `nodejs_compat_v2` to get v2 early; between 2024-09-23 and 2026-08-03 it could add `no_nodejs_compat_v2` to stay on v1. From 2026-08-04 the positive flags are redundant: Wrangler, Miniflare, the Vite plugin and the Vitest plugin drop them before starting the runtime, so an old configuration keeps working after a bump, and new configurations omit them. ## Opting out takes two flags `nodejs_compat` and `nodejs_compat_v2` are separate runtime flags, and from 2026-08-04 the date turns on **both**. Listing only `no_nodejs_compat` switches off the base flag but leaves v2 on, so the `Buffer` and `process` globals and modules such as `node:crypto` stay available while the date-gated extras (`node:fs`, the populated `process.env`) disappear. Turning Node.js compatibility off completely needs `no_nodejs_compat` **and** `no_nodejs_compat_v2`. A team that wants only `AsyncLocalStorage` can instead use `nodejs_als` on a date without Node.js compatibility. ## What rides on the date as well Node.js compatibility is not one switch frozen in 2024. Many module-level changes are implied by `nodejs_compat` after their own date, so the same flag means more on a newer date: - `nodejs_compat_populate_process_env` (2025-04-01): `process.env` filled from text and JSON bindings. - `enable_nodejs_http_modules` (2025-08-15): client `node:http` and `node:https`. - `enable_nodejs_fs_module` and `enable_nodejs_process_v2` (2025-09-15): the virtual filesystem and the full `process` object. - `enable_nodejs_global_timers` (2026-02-10): `setTimeout` returns a Node.js-style `Timeout` object. - Stub modules such as `node:child_process` (2026-03-17). Each has a disable flag (`disable_nodejs_fs_module`, `no_nodejs_global_timers`, ...) for holding one back. ## Telling the tiers apart from the error The message says which layer a failure comes from: - `No such module "node:crypto"` at load time: Node.js compatibility (or that module's own flag) is off for this date. - `Could not resolve "crypto"` at build time: a bare import without v2, which is what accepts names without the `node:` prefix. - `[unenv] fs.writeFileSync is not implemented yet!` when a method runs: the module came from a Wrangler polyfill, not the runtime. - `The child_process.execSync method is not implemented` when a method runs: the module is one of the runtime's stubs. ## Why a team might keep it off v2 makes Wrangler bundle extra polyfills and globals, which grows the Worker. A Worker with no Node.js dependencies gains nothing from it, and some teams prefer the smaller bundle and the narrower API surface. With the default flipped, keeping it off is now an explicit decision written into the configuration, not the absence of a flag. ## Things it does not change `node_compat = true`, Wrangler 2's bundler-only polyfill switch, was removed in Wrangler 4; `nodejs_compat` is the only mechanism. Node.js compatibility also does not lift Workers' limits: CPU time, memory and subrequest limits stay the same, and the virtual `fs` is in memory (`/bundle` read-only, `/tmp` writable per request), not a disk.

  • A Worker dated 2026-10-01 lists only no_nodejs_compat. Is Node.js compatibility off?
    Only partly. The date turns on both `nodejs_compat` and `nodejs_compat_v2`, and the single disable flag switches off only the first. v2 stays on, so `Buffer`, `process` and modules such as `node:crypto` still work, while date-gated extras implied by the base flag, such as `node:fs` and a populated `process.env`, go away. Add `no_nodejs_compat_v2` as well to turn it off completely.
  • Why might a team keep Node.js compatibility off on a new Worker?
    v2 makes Wrangler bundle extra polyfills and globals, which increases the Worker's size, and a Worker with no Node.js dependencies gains nothing from them. Keeping it off also narrows the API surface reviewers have to reason about. Since 2026-08-04 that choice has to be written down with both disable flags.
  • How does a Worker get AsyncLocalStorage without the rest of Node.js compatibility?
    List `nodejs_als` in `compatibility_flags`. It enables only the AsyncLocalStorage API from `node:async_hooks`, independently of `nodejs_compat`, which is useful for request-scoped context in a Worker that otherwise has no Node.js dependencies.

  • nodejs_compat turns a Worker into a Node.js process that runs any npm package.
  • Every Node.js module works fully once nodejs_compat is on.
  • Adding no_nodejs_compat alone disables Node.js APIs on a 2026-10 date.
  • New Workers must still list nodejs_compat to import node:crypto.
  • Setting node_compat = true in the Wrangler file adds the Node.js polyfills.

Assumes Cloudflare Workers as of 2026-10-10: nodejs_compat and nodejs_compat_v2 are on by default for compatibility dates from 2026-08-04, opt-in before; node_compat was removed in Wrangler 4.