skip to content

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%

answer

  1. two kinds of change in one deploy
  2. No such module before the bump
  3. every flag dated in between
  4. polyfills throw only when called
  5. disable flag to hold one back

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.

solid answer

~40 s

On 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 lines
javascript
export default {
  async fetch(request) {
    const timer = setTimeout(() => {}, 1000);
    const kind = typeof timer;
    clearTimeout(timer);
    return new Response(kind);
  },
};

go deeper

for a junior

Recall that an old Worker without Node.js compatibility cannot import node:crypto, and that a newer date turns it on by default.

for a middle

Explain that a bump turns on every change dated between the two dates, and how a disable flag holds one back.

for a senior

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.

for a principal

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.