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.

```jsonc
{
  "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.