Upgrade to Node.js 24

Node 24 (Krypton) is the active LTS — released 2025-05-06, promoted to LTS on 2025-10-28, and supported until 2028-04-30 — and the recommended target for apps on Node 16, 18, or 20 (all end-of-life). Most breakage comes from native-module ABI rebuilds, removed deprecated APIs, and the OpenSSL 3 baseline, not from rewriting code. Budget half a day to three days depending on how many native dependencies you ship and how big the version gap is.

Who should upgrade

• Anyone still on Node 16, 18, or 20 — all three are end-of-life and receive no security patches.
• Teams that want require() of synchronous ES modules by default, the stable permission model (--permission), global URLPattern, and native .env file support.
• Services that want built-in fetch/WebSocket (Undici 7) and to drop a node-fetch/ws polyfill dependency.

Who should wait (use Node 22 instead)

• Apps blocked by a critical native dependency without a Node 24-compatible prebuilt binary — pin to the Node 22 maintenance LTS rather than staying on an EOL major.
• Windows build pipelines that still rely on MSVC: Node 24 drops MSVC and requires ClangCL to compile from source.
• Builds depending on APIs removed in Node 24 (url.parse runtime deprecation, tls.createSecurePair removal, SlowBuffer) until the code is fixed.

What changed since Node 20

• require() of synchronous ES modules is enabled by default (unflagged since Node 22.12; no experimental warning in Node 24).
• The Permission Model is stabilized: the flag is now --permission (was --experimental-permission).
• Built-in WebSocket client is enabled by default since Node 22; Node 24 ships Undici 7 with stricter fetch compliance and WebSocketStream.
• URLPattern is exposed as a global; native .env file loading is supported.
• V8 upgraded to 13.6 (Float16Array, RegExp.escape, explicit resource management, Error.isError, WebAssembly Memory64) and the bundled npm is npm 11.
• AsyncLocalStorage now defaults to AsyncContextFrame for better performance.
• Removed/deprecated APIs: url.parse() runtime-deprecated (use the WHATWG URL API), tls.createSecurePair removed, SlowBuffer runtime-deprecated, dirent.path removed.
• Windows: MSVC support removed; ClangCL is required to build Node from source.

⚠ Rebuild native modules before debugging runtime failures

A new Node major bumps the V8/N-API ABI, so any package with native bindings (binding.gyp, prebuilt .node files) must be reinstalled or rebuilt with npm rebuild. Moving from an EOL major to Node 24 can cross several ABI versions, so 'mysterious' crashes right after the upgrade are usually stale native addons, not application bugs.

Recommended upgrade path

Fast path for a service moving onto the Node 24 LTS

# 1. Pin the new version locally
nvm install 24 && nvm use 24
node --version  # v24.x

# 2. Reinstall and rebuild native modules against the new ABI
rm -rf node_modules && npm ci
npm rebuild

# 3. Run the test suite on Node 24
npm test

LTS support matrix

AI-assisted migration workflow

Upgrade this project to Node.js 24 LTS. First inspect engines.node, .nvmrc, the CI node-version matrix, the Docker base image, and any native dependencies. Then bump the engine and pin .nvmrc, update CI and Docker, run `npm ci` followed by `npm rebuild`, and run the test suite. Triage failures: rebuild native modules first, then check for APIs removed/deprecated by Node 22–24 (url.parse, tls.createSecurePair, SlowBuffer) and any OpenSSL 3 fallout. On Windows, confirm the build toolchain uses ClangCL, not MSVC. Run install and tests after each step and report before continuing.

Safety: Incremental edits only. Pause for review after the engine/CI changes and after the native rebuild. Do not silently upgrade unrelated dependencies.

PR review checklist

• engines.node, .nvmrc, the CI matrix, and the Docker base image all reference Node 24
• node_modules was reinstalled and native modules rebuilt against the new ABI
• No removed/deprecated Node APIs remain in changed code paths (url.parse, tls.createSecurePair, SlowBuffer)
• Any node-fetch/ws used only as a polyfill was reviewed against built-in fetch/WebSocket
• Windows builds use ClangCL (MSVC is no longer supported)
• No new Node deprecation warnings appear in the test output

Rollback strategy

• Keep the engine bump, CI/Docker changes, and native rebuild in separate commits.
• If a blocking native incompatibility appears, fall back to the Node 22 maintenance LTS — never back to an EOL major — and reinstall.
• Hold the upgrade behind a release branch until the full test suite is green on Node 24 in CI.

Common errors

• 'Module did not self-register' or 'NODE_MODULE_VERSION' mismatch — rebuild native modules with npm rebuild.
• DeprecationWarning for url.parse() — migrate to the WHATWG URL API (new URL()).
• TLS/crypto errors after the OpenSSL 3 baseline — see the fix-node-dependency-errors workflow.
• 'engine "node" is incompatible' from a dependency — find a Node 24-compatible release or replacement.

Related migration paths

• Migrate Node.js CommonJS to ES Modules — Related path
• Node.js 16 to Node.js 20 Migration Guide — Related version path
• Node.js 18 to Node.js 20 Migration Guide — Related version path
• Node.js 18 to Node.js 24 Migration Guide — Upgrade path to same target
• Node.js 20 to Node.js 24 Migration Guide — Upgrade path to same target
• Upgrade to Node.js 20 — Related version path
• Fix Node.js Dependency Errors — Earlier step in the upgrade chain

Official sources

• Node.js 24.11.0 'Krypton' (LTS) — nodejs/node (reliability 92%)
• Node.js 24 is now available! — nodejs.org (reliability 98%)
• Node.js ECMAScript Modules — nodejs.org (reliability 98%)
• Node.js Release Working Group — release schedule — nodejs/Release (reliability 98%)

Copy-ready AI prompts

Structured prompts for an AI coding assistant. Inspect first, then execute incrementally, and keep a human in the review loop.

Repo inspection: Repo inspection prompt

You are helping with a Node.js migration: upgrade to Node.js 24 LTS.

Do not edit files yet. First inspect the repository and report:
1. The current Node version targets: the "engines.node" field in package.json, the .nvmrc / .node-version file, and the node-version used in CI (.github/workflows/*.yml) and any Dockerfile base image.
2. The module system: whether package.json sets "type": "module", and the mix of .js / .cjs / .mjs files.
3. Native modules (packages with binding.gyp or install scripts) that must be rebuilt against the new ABI.
4. Usage of deprecated or removed APIs surfaced by the new major's deprecations (e.g. legacy url.parse patterns, the old assert API, removed crypto/buffer constructors).
5. The install, build, and test commands and whether the lockfile is committed.

Return: a risk summary, the highest-risk files and dependencies, a suggested migration order, the commands to run before editing, and any questions that need human confirmation.

Safety: Inspection only. The agent must not modify files in this step.

Works with Claude Code, Cursor, GitHub Copilot.

Migration execution: Migration execution prompt

Perform the migration (upgrade to Node.js 24 LTS) one concern at a time.

Work in this order and pause for review after each: (1) bump "engines.node" in package.json and pin the new version in .nvmrc, (2) update every CI matrix entry and Docker base image to the new Node version, (3) reinstall and rebuild native modules with `npm rebuild`, (4) run the test suite and triage runtime failures, (5) replace any deprecated/removed APIs surfaced during inspection.

After each step run the project's install and test commands and report results before continuing. Do not bundle unrelated refactors or upgrade dependencies that are not required by the Node bump.

Safety: Apply changes incrementally and keep each step reviewable. Rebuild native modules before assuming a failure is a code problem.

Works with Claude Code, Cursor, GitHub Copilot.

Test plan

Commands

• node --version
• npm ci
• npm rebuild
• npm test
• npm run build

Manual checks

• Native modules: confirm packages with native bindings load without ABI/version errors at runtime.
• Startup: boot the app on the new Node version and watch for new deprecation warnings.
• Globals: verify code relying on built-in fetch, the test runner, or other newly-stable APIs behaves the same locally and in CI.

Regression risks

• Native addons compiled against the old ABI failing to load until rebuilt.
• Deprecated APIs removed in the new major breaking code paths not covered by tests.
• Dependencies that declare an engines range excluding the new Node version.

Acceptance criteria

• Install, build, and the full test suite pass on the target Node version.
• CI, .nvmrc, and the Docker image all reference the same Node version.
• No new Node deprecation warnings appear in the test output.

Frequently asked questions

Is Node 24 the right target, or should I use Node 22?

Node 24 (Krypton) is the active LTS and the default recommendation — it has the longest support window (to 2028-04-30). Node 22 (Jod) is the maintenance LTS (to 2027-04-30) and a reasonable fallback only if a critical dependency is not yet Node 24-compatible. Do not target Node 16, 18, or 20 — all are end-of-life.

Do I have to remove node-fetch and ws now that fetch and WebSocket are built in?

No. Built-in fetch is stable since Node 21 and the built-in WebSocket client is enabled by default since Node 22, so both are available on Node 24 without a polyfill. Keeping node-fetch/ws still works; removing them is an optional cleanup once you confirm the built-ins match your usage.

What broke between Node 20 and Node 24?

Mostly removed or runtime-deprecated APIs rather than application-level rewrites: url.parse() is runtime-deprecated (use new URL()), tls.createSecurePair is removed, SlowBuffer and REPL/zlib construction without new are deprecated, and dirent.path is removed. On Windows, MSVC is no longer supported and ClangCL is required to build from source. Native modules must be rebuilt across the ABI bumps.