workers-types declares Buffer and process as const, discarding the @types/node globals

[kingmesal]

@cloudflare/workers-types declares Buffer and process as const, which discards the @types/node globals in any project that uses both.

index.d.ts (lines 486–487 in 5.20260817.1):

declare const Buffer: any;
declare const process: any;

@types/node declares var Buffer: BufferConstructor inside declare global { … } in buffer.buffer.d.ts. A var merges across declaration files; a block-scoped const does not. The redeclaration discards the @types/node global block, and ordinary Node code stops type-checking.

Affected: any project listing both @cloudflare/workers-types and node in compilerOptions.types.

First affected version	5.20260807.2
Last clean version	5.20260804.1
Still present in	5.20260817.1 (current latest)

Bisected by unpacking each published tarball and grepping index.d.ts, so the boundary is exact rather than inferred from a changelog. Ten consecutive releases now carry it.

Reproduction

package.json — @cloudflare/workers-types@5.20260817.1, @types/node@22.20.1, typescript@5.9.3.

tsconfig.json:

{
  "compilerOptions": {
    "types": ["node", "@cloudflare/workers-types"],
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["src"]
}

src/index.ts:

import { randomBytes } from "node:crypto";
export const id = (): string => randomBytes(8).toString("hex");

tsc --noEmit:

src/index.ts(2,50): error TS2554: Expected 0 arguments, but got 1.

The real error, which skipLibCheck hides

With skipLibCheck: false TypeScript states the actual problem:

node_modules/@cloudflare/workers-types/index.d.ts(486,15): error TS2451: Cannot redeclare block-scoped variable 'Buffer'.
node_modules/@types/node/buffer.buffer.d.ts(356,19): error TS2451: Cannot redeclare block-scoped variable 'Buffer'.

skipLibCheck: true — the default in most templates, including Cloudflare's own — suppresses the TS2451 and leaves only the downstream TS2554. That is why this presents as a mystery about randomBytes rather than as a redeclaration. A type probe shows randomBytes(8).toString resolving to () => string, i.e. Uint8Array.prototype.toString, because the Buffer interface members in the discarded global block are gone.

Isolated

Each row run, not reasoned about:

change	result
types order reversed	still fails — ordering is irrelevant
types: ["node"] alone	clean
pin 5.20260804.1	clean
declare const → declare var on both lines	clean
delete both lines	clean
delete the process line only	still fails — Buffer alone is the cause
delete the Buffer line only	clean

process has the same collision, and it is silent

declare const process: any collides with @types/node's var process identically. It produces no error only because any absorbs every member access — so rather than failing, it silently degrades process from NodeJS.Process to any. Anyone with both type sets has lost that typing without being told.

Suggested fix

Declare them as var, which merges with @types/node rather than colliding with it:

declare var Buffer: any;
declare var process: any;

Or do not emit them at all — a Workers project that wants Buffer or process types installs @types/node and sets nodejs_compat, and gets the real declarations rather than any.

Prior art

cloudflare/workerd#1298 — "Transitive loading of @types/node breaks Request/Response (etc.) types" — is the same collision class pointing the other way: @types/node clobbering workers-types when Node began declaring its own Request/Response. This is the mirror image.

---

Found while pinning dependency floors ahead of a first release of a Workers framework built on workerd. Happy to open a PR with the const → var change if that is the preferred fix.

[aayushbaluni]

Reproduced this and ran the proposed fix against a real tsc. The diagnosis holds, but the fix as written is one name short, and the obvious generalisation of it is actively harmful. Details, since both matter for whatever patch lands.

Reproduction — @cloudflare/workers-types@5.20260817.1, @types/node@22.20.1, typescript@5.9.3, your exact tsconfig.json and src/index.ts:

src/index.ts(2,57): error TS2554: Expected 0 arguments, but got 1.

global collides too. With skipLibCheck: false there are three TS2451s from index.d.ts, not two:

index.d.ts(486,15): error TS2451: Cannot redeclare block-scoped variable 'Buffer'.
index.d.ts(487,15): error TS2451: Cannot redeclare block-scoped variable 'process'.
index.d.ts(488,15): error TS2451: Cannot redeclare block-scoped variable 'global'.

@types/node declares var global at globals.d.ts(1,13), so declare const global: ServiceWorkerGlobalScope on line 488 has exactly the same problem. It sits directly under the two you found.

Measured, one variant per run, counting TS2451 under --skipLibCheck false:

variant	app build	remaining TS2451
as published	TS2554	3
const→var for Buffer, process (as proposed)	clean	1 (global)
const→var for Buffer, process, global	clean	0
const→var for every top-level declare const	clean	0, but 8 new TS2403

The app-level build goes clean under all three, which is why the missing global is easy to miss: it only shows up with skipLibCheck: false.

Why the blanket version is wrong. Rewriting every top-level declare const introduces new errors, because var merges and merging demands identical types:

TS2403: ... Variable 'self' must be of type ...
TS2403: ... Variable 'Request' must be of type ...
TS2403: ... Variable 'Response' must be of type ...
TS2403: ... Variable 'ReadableStream' must be of type ...
TS2403: ... Variable 'WebSocket' must be of type ...
TS2403: ... Variable 'onmessage' must be of type ...

(8 in total, all from index.d.ts.) const is doing real work for self, Request, Response, ReadableStream and WebSocket: it keeps the Workers definitions from being merged with the DOM ones they intentionally differ from. So this should not become "emit var for globals" in the generator at types/src/transforms/globals.ts:107-110, where the flag is currently hardcoded:

const varDeclarationList = ctx.factory.createVariableDeclarationList(
  [varDeclaration],
  ts.NodeFlags.Const // Use `const` instead of `var`
);

The distinction that actually predicts the right answer is whether the name is also declared by @types/node. Buffer, process and global are Node globals that workerd exposes under nodejs_compat_v2 (global-scope.h:962-964), and for those merging is the desired behaviour. self, crypto, caches, performance, navigator and friends are Workers/DOM globals where merging is not.

So the narrow fix is a small allowlist of Node-owned names emitted as var, everything else unchanged. That is also consistent with your second suggestion of not emitting them at all — but var keeps globalThis.Buffer resolving for people who do not have @types/node, so it seems the safer of the two.

Caveats, stated plainly. I verified this by patching the published index.d.ts in node_modules and re-running tsc, which measures the fix but not the generator change that would produce it. I have not yet built workerd or regenerated the types (bazel toolchain is only half set up on this machine), so I have not confirmed the generator emits exactly this. The TS6200/TS2717 noise under skipLibCheck: false is pre-existing and unrelated; I ignored it and only tracked TS2451/TS2403.

Also worth noting the process half is not merely cosmetic, as you say: declare const process: any does not error, it silently replaces NodeJS.Process with any. Nobody gets told.

@jasnell — happy to open a PR for the allowlist approach in globals.ts if that shape sounds right, though I would want to regenerate and diff the full index.d.ts first to be sure nothing else moves.