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?
answer
- two kinds of change in one deploy
- No such module before the bump
- every flag dated in between
- polyfills throw only when called
- disable flag to hold one back
basics
~20 sBefore 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.
solid answer
~40 sOn the old date with no flag, importing `node:crypto` stops the Worker loading with `No such module "node:crypto"`, and a bare `Buffer` is undefined; a date from 2026-08-04 turns Node.js compatibility on by default and fixes that. But the bump also applies every gated change dated in between: `fetch()` drops `Authorization` on cross-origin redirects from 2025-09-01, `setTimeout()` returns a `Timeout` object from 2026-02-10, and `process.env` is populated from bindings. Modules the runtime lacks come as unenv polyfills or stubs that throw only when a method is called. I would read the flags history between the two dates, ship the bump separately from the library, run `wrangler dev` and tests at the new date, grep for `[unenv]` errors, and hold back any one change with its disable flag.
code
javascript · 8 linesexport default {
async fetch(request) {
const timer = setTimeout(() => {}, 1000);
const kind = typeof timer;
clearTimeout(timer);
return new Response(kind);
},
};go deeper
Recall that an old Worker without Node.js compatibility cannot import node:crypto, and that a newer date turns it on by default.
Explain that a bump turns on every change dated between the two dates, and how a disable flag holds one back.
Show the diagnosis: diff the flags history, ship the bump alone, run at the new date locally, find unenv and stub errors, and roll out gradually.
Treat a large date jump as a runtime upgrade with release notes, and push for small, regular bumps so no single deploy carries two years of changes.
## The situation A Worker was written two years ago with `compatibility_date` set to `2024-10-01` and no flags. Now the team adds an npm library that does `import { createHash } from "node:crypto"` and uses `Buffer` as a global, and moves the date to `2026-10-01` so the library will load. Two different kinds of change arrive in the same deploy, and a good diagnosis keeps them apart. ## Failure 1: the library cannot load on the old date On `2024-10-01` without any flag the Worker has **no Node.js compatibility**. Wrangler's bundler sees an import of a built-in it cannot find and warns: ```plaintext The package "node:crypto" wasn't found on the file system but is built into node. Your Worker may throw errors at runtime unless you enable the "nodejs_compat" compatibility flag. ``` The build still succeeds, but the runtime cannot load the Worker: `Uncaught Error: No such module "node:crypto".` A bare `Buffer` would be a `ReferenceError: Buffer is not defined`. Older setups show variants of the same problem: - With `nodejs_compat` on a date **before 2024-09-23** (v1), a bare `import ... from "crypto"` fails the build with `Could not resolve "crypto"` and the hint to use the `node:` prefix or a date of 2024-09-23 or later; `Buffer` is still not a global. - On dates from 2024-09-23 with the flag (v2), imports with or without `node:` work and `Buffer` and `process` are globals. Moving the date to `2026-10-01` fixes all of this at once, because from 2026-08-04 Node.js compatibility is on by default. ## Failure 2: everything else the new date turns on The bump is not a Node.js switch; it is **every gated change dated between the two dates**, and it lands with the library. Examples from that window: | Change | Date | What can break | |---|---|---| | `nodejs_compat_populate_process_env` (with Node.js compatibility) | 2025-04-01 | libraries now find vars and secrets in `process.env` and change behaviour | | `strip_authorization_on_cross_origin_redirect` | 2025-09-01 | `fetch()` no longer forwards `Authorization` when an API redirects to another host | | `enable_nodejs_global_timers` (with Node.js compatibility) | 2026-02-10 | `setTimeout()` returns a `Timeout` object, not a number | The timer change is a good example of a silent break: code that stored the timer id in a numeric field or serialised it now handles an object with `refresh()`, `ref()`, `unref()` and `hasRef()`. ## Failure 3: a module that loads but throws Node.js compatibility has three tiers. Modules workerd implements natively work. Modules it does not implement are filled by **unenv** polyfills that Wrangler bundles: the import succeeds and an unimplemented method throws `[unenv] fs.writeFileSync is not implemented yet!` at the moment it is called. That is what `node:fs` did on a 2025-01-01 date; from 2025-09-15 the runtime implements a virtual `fs`. A third group, such as `node:child_process`, are **stubs**: on a current date `execSync` throws `The child_process.execSync method is not implemented`. Each of these fails only on the code path that calls it, so a smoke test of the home page passes. ## How to find the breakage 1. **Diff the dates.** Read the compatibility flags history for every change between the old and new date and mark the ones the code touches. 2. **Bump on its own.** Ship the date change separately from the library, so a regression points at one cause. 3. **Run at the new date locally.** `wrangler dev` runs the same runtime with the same date and flags; exercise the paths that use redirects, timers, `process.env` and the library's calls, and the test suite under the new date. 4. **Search for polyfill errors.** Grep logs and test output for `[unenv]` and `is not implemented`, which point at a method the runtime does not provide. 5. **Hold back one change.** If one change needs code work, add its disable flag (`retain_authorization_on_cross_origin_redirect`, `no_nodejs_global_timers`) and take the rest, then remove the flag once fixed. 6. **Roll out gradually.** Each Worker version carries its own date, so a gradual deployment exposes the new date to a slice of traffic first. ## The lesson A date bump is a dependency upgrade of the runtime, with release notes. The library is the reason for the bump, but the riskiest part of it is often everything else that came with it.
- Why does a smoke test often pass after the bump even though production later throws?Polyfilled and stub modules load without error; only calling an unimplemented method throws, such as `[unenv] fs.writeFileSync is not implemented yet!` or `The child_process.execSync method is not implemented`. Behaviour changes such as the stripped `Authorization` header affect only the code path that follows a cross-origin redirect. A home-page check exercises neither, so the tests must cover the library's real calls.
- The team needs the new date now but an upstream API relies on Authorization surviving a redirect to another host. What do they do?Keep the new date and add `retain_authorization_on_cross_origin_redirect` to `compatibility_flags`, which restores only that behaviour. Record the flag as debt with a trigger, then fix the call, for example by following the redirect explicitly and deciding whether the new host should receive the credential, and remove the flag.
- Bumping the date only turns on Node.js compatibility and nothing else.
- If the Worker builds, every imported Node.js module works at runtime.
- Rolling back the library alone undoes the compatibility date bump.
- A Node.js import error after a bump means the npm package is broken.
- The only way to avoid one breaking change is to keep the old date.
Assumes Cloudflare Workers as of 2026-10-10: Node.js compatibility is on by default for compatibility dates from 2026-08-04, and the listed changes carry the enable dates shown.