Bump @types/node from 20.19.41 to 25.9.3

[dependabot]

Bumps @types/node from 20.19.41 to 25.9.3.

Commits

• See full diff in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

---

Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR:

• @dependabot rebase will rebase this PR
• @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
• @dependabot show <dependency name> ignore conditions will show all of the ignore conditions of the specified dependency
• @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)

[desrosj]

@copilot I want you to examine what is being updated within this pull request, analyze how the dependency is used, and clearly document every way the repository utilizes it.

I then want you to analyze the upstream changes being merged in this update to determine if this has high, medium, low, or no risk for introducing problems.

I also want you to report on what the possible issues are as a result of this update and create a plan for how to address each compatibility issue. When you are able to, please comment with the specific change suggestions for any changes that should be made to properly prepare and support this update. Make sure to reference the point in the detailed analysis each change suggestion addresses.

And finally, I want you to analyze whether this dependency can be removed entirely in favor of a native-first solution, or making use of other code in this repository.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props desrosj.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[Copilot]

@copilot I want you to examine what is being updated within this pull request, analyze how the dependency is used, and clearly document every way the repository utilizes it.

I then want you to anal...

@types/node 20 → 25 Analysis

---

1. How the repository uses @types/node

The package serves two roles:

A. Global type scope (via tsconfig.json)

tsconfig.json lists "node" in its "types" array, which makes all Node.js built-in globals (process, Buffer, __dirname, __filename, etc.) available across every file in the type-checked set. The six type-checked files are:

File	Role
src/js/_enqueues/wp/code-editor.js	Browser-side (admin code editor)
src/js/_enqueues/lib/codemirror/javascript-lint.js	Browser-side (CodeMirror JS linting)
src/js/_enqueues/lib/codemirror/htmlhint-kses.js	Browser-side (CodeMirror HTML linting)
tools/gutenberg/copy.js	Node.js build script
tools/gutenberg/download.js	Node.js build script
tools/gutenberg/utils.js	Node.js build script

B. Explicit JSDoc type annotations

Two explicit @types/node type references exist:

// tools/gutenberg/utils.js (lines 203, 227)
const err = /** @type {NodeJS.ErrnoException} */ ( error );

// tools/gutenberg/download.js (line 193)
/** @type {import('stream/web').ReadableStream} */ ( response.body )

C. Implicit module types

The three Gutenberg scripts use Node.js built-in modules via require() whose type definitions come entirely from @types/node: fs, path, child_process, stream/promises, and zlib.

---

2. What changed between v20.19.41 and v25.9.3

The package-lock.json diff shows two changed packages:

Package	Old	New
@types/node	20.19.41	25.9.3
undici-types	6.21.0	7.24.6

@types/node changes (v20 → v25):

• New module type files: quic.d.ts (QUIC protocol, experimental), sqlite.d.ts (built-in SQLite, Node.js 22.5+), wasi.d.ts (WASI, now stable)
• New compatibility/iterators.d.ts: A backwards-compatibility shim for TypeScript 5.6+ iterator helper methods on Node.js iterators
• API additions across Node.js 21–25 now typed: fs.glob() (Node.js 22+), new QUIC APIs, additional crypto methods, etc.
• No removals of types the codebase currently uses

undici-types changes (6.x → 7.x):

undici-types provides the type definitions for the global fetch, Request, Response, Headers, and ReadableStream in Node.js. The Response.body property remains ReadableStream | null in v7, with ReadableStream imported from node:stream/web — consistent with how download.js already uses it.

---

3. Risk Assessment: LOW

Confirming factors:

• npm run typecheck:js passes with zero errors after the update
• NodeJS.ErrnoException is unchanged in v25 — the two explicit type annotations in utils.js remain valid
• import('stream/web').ReadableStream resolves identically in v25 — the download.js type cast is unaffected
• No deprecated or removed APIs affect the current codebase

One structural concern worth noting:

@types/node is versioned to match the corresponding Node.js major release. The repository's engines field requires Node.js >=20.10.0 and .nvmrc pins to 20. Using @types/node@25 means the type checker will accept any Node.js 21–25 API (e.g., fs.glob(), new crypto methods) as valid, even if that code would fail at runtime on Node.js 20. There is no type error today, but this creates a documentation gap between the declared minimum Node.js version and the types used to validate the code.

---

4. Issues and plan

Issue A – Version mismatch between @types/node and engines.node / .nvmrc

Impact: Low. No currently written code uses a Node.js 21+ API, but future contributors could write code using an API from Node.js 22+ (e.g., fs.glob()) that passes the type checker while failing at runtime on the declared minimum Node.js 20.

Options (in order of preference):

1. Align @types/node version to Node.js version — Keep @types/node in sync with the actual Node.js minimum. Since the project targets >=20.10.0, @types/node@20 is the correct corresponding type package. This approach is used by most projects and makes the type checker enforce compatibility accurately.

2. Bump the declared Node.js minimum to Node.js 22 LTS — Node.js 20 reaches End-of-Life in April 2026, and Node.js 22 is the current active LTS (maintenance until April 2028). If the project can move to engines: { node: ">=22.0.0" } and update .nvmrc to 22, then @types/node@22 (or 25, which is a superset) would be the appropriate package.

3. Accept the mismatch — Keep @types/node@25 as Dependabot proposed. There is no immediate breakage. The risk is that future code could inadvertently use a newer API without a type error.

Suggested change for option 1 (reverting the Dependabot bump to stay aligned with the current Node.js target):

// package.json
"@types/node": "20.19.41"  // matches .nvmrc: 20 and engines >=20.10.0

Suggested change for option 2 (align the Node.js minimum with @types/node@25):

// package.json engines
"engines": {
  "node": ">=22.0.0",
  "npm": ">=10.2.3"
}
// .nvmrc
22

The Gutenberg tools use fetch() as a global, which became stable in Node.js 21, so raising the minimum to 22 would actually tighten correctness as well.

---

Issue B – Browser-side files receive all Node.js globals unnecessarily

Impact: Very low. No actual type errors result, but process, Buffer, __dirname, etc. appear as valid globals in code-editor.js, javascript-lint.js, and htmlhint-kses.js, which are browser-side files that should never use them.

Root cause: tsconfig.json has a single "types": ["node", ...] that applies to all six files, including the three browser-side ones.

Suggested change: Split the tsconfig.json into two configurations — one for the browser-side files (without "node" in types) and one for the Gutenberg scripts (with "node"). This is a non-trivial refactor but would make type checking stricter and more accurate for the browser files. For now, this is a low-priority improvement.

---

5. Can @types/node be removed entirely?

No — not without significant refactoring. The three Gutenberg scripts (copy.js, download.js, utils.js) directly use Node.js built-in module types (fs, path, child_process, stream, zlib) and the NodeJS.ErrnoException interface. These all come from @types/node. Removing the package would require either disabling type checking for these scripts or providing alternative type stubs.

The two specific type annotations could be replaced with inline equivalents:

• NodeJS.ErrnoException → Error & { code?: string | undefined } (no package required)
• import('stream/web').ReadableStream → ReadableStream (WHATWG ReadableStream is already a DOM global)

But the implicit module types for fs, path, etc. have no built-in replacement in the TypeScript ecosystem today. @types/node is a necessary devDependency for this codebase.

---

Summary

The update is safe — npm run typecheck:js passes with no errors. The one decision worth making deliberately is whether to align @types/node with the declared Node.js minimum (engines >=20.10.0 / .nvmrc: 20) rather than accepting the jump to v25 types. Given that Node.js 20 reaches End-of-Life in April 2026, this is also a good time to consider whether the Node.js minimum itself should be bumped to Node.js 22 LTS, which would make the v25 type update more appropriate.

[dependabot]

A newer version of @​types/node exists, but since this PR has been edited by someone other than Dependabot I haven't updated it. You'll get a PR for the updated version as normal once this PR is merged.