skip to content

Compatibility Dates & Node APIs

A compatibility_date pins runtime behaviour per Worker; from 2026-08-04 it also turns on the Node.js APIs that older Workers opt into with nodejs_compat. Interviewers ask what a date bump changes.

on this pageshow

explore

questions

5

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.

open as a page

In Cloudflare Workers, what does a Worker's compatibility_date pin, and how do compatibility_flags adjust what that date turns on?

level: middleimportance: should knowfreq 42%

basics

~20 s

A compatibility_date gives a Worker every gated runtime change dated on or before it, so its behaviour holds until the team changes the date and redeploys. compatibility_flags enable one change early or keep one off.

open as a page

A team bumps a two-year-old Cloudflare Worker's compatibility_date to add an npm library using node:crypto and Buffer; what can break, and how do they find it?

level: seniorimportance: should knowfreq 35%

basics

~20 s

Before the bump the library cannot load (no Node.js compatibility). After it, every runtime change dated in between also applies, such as stripped Authorization on cross-origin redirects and object-valued timers, and unenv-polyfilled methods throw when called.

open as a page

In Cloudflare Workers, an npm SDK reads process.env.API_KEY and gets undefined although the secret is set; why, and what fixes it?

level: seniorimportance: should knowfreq 30%

basics

~20 s

process.env is filled from vars, secrets and version metadata only when Node.js compatibility is on and the compatibility date is 2025-04-01 or later (or nodejs_compat_populate_process_env is set). Otherwise it is empty, so move the date, add the flag, or pass env.API_KEY explicitly.

open as a page

As the lead for a team running dozens of Cloudflare Workers, what rule would you set for bumping compatibility dates, and why?

level: principalimportance: should knowfreq 24%

basics

~20 s

Bump on a regular cadence, in a change of its own that lists the flags dated in the window, tested and rolled out gradually at the new date. Set a maximum age, track every disable flag as debt, and decide the Node.js default deliberately.

open as a page