VVersions.dev

Node.js 20 → Node.js 24

Node 20 reached end-of-life on 2026-04-30, so moving to the active Node 24 LTS is a security upgrade, not an optional one. It is two LTS majors (20 → 22 → 24) but you go directly to 24 — the work is bumping version pins, rebuilding native modules across the ABI gap, and clearing removed/deprecated APIs (url.parse, tls.createSecurePair).

Version upgradeDifficulty: moderateEffort: 0.5–3 daysmedium risk

Last verified · Updated May 22, 2026

Node 20 is end-of-life (since 2026-04-30) and Node 24 (Krypton) is the active LTS, so go directly to 24 — there is no benefit to stopping at the Node 22 maintenance line unless a dependency forces it. The jump spans two LTS majors, so expect a larger native-module ABI bump and a few removed/deprecated APIs to clear, but no broad application rewrite.

Should you upgrade directly?

Yes — go straight to Node 24. Node 22 is only a maintenance LTS (EOL 2027-04-30), so stopping there adds work without much runway. The public APIs are largely compatible across 20 → 24; the friction is the ABI bump for native modules, the url.parse runtime deprecation and tls.createSecurePair removal, and (on Windows build pipelines) the move from MSVC to ClangCL.

Key differences

  • require() of synchronous ES modules is on by default in Node 24 (was experimental on 20).
  • Permission Model is stable: the flag is now --permission (was --experimental-permission).
  • Built-in WebSocket client is enabled by default (since 22); Node 24 ships Undici 7 with WebSocketStream.
  • URLPattern is a global; native .env file loading is supported.
  • V8 13.6 and bundled npm 11 (Node 20 shipped V8 11.3 and npm 9).
  • Removed/deprecated: url.parse() runtime-deprecated, tls.createSecurePair removed, SlowBuffer deprecated, dirent.path removed.
  • Windows: MSVC dropped, ClangCL required to build from source.

Files and patterns to inspect

  • engines.node in package.json and the committed .nvmrc / .node-version.
  • The node-version matrix in .github/workflows/*.yml.
  • The Docker base image (FROM node:20...).
  • Dependencies with native bindings (binding.gyp, prebuilt .node files).
  • Code using url.parse(), tls.createSecurePair, or SlowBuffer.

Pre-migration checklist

  • Green test suite on Node 20 before starting
  • Lockfile committed; dependencies audited for Node 24 engine support
  • A dedicated upgrade branch
  • url.parse / legacy crypto usage inventoried for review

ℹ Update CI and Docker in the same change as the engine bump

Drift between .nvmrc, the CI matrix, and the Docker base image is a top source of 'works on my machine' failures. Change all four pins (engines.node, .nvmrc, CI node-version, Dockerfile FROM) in one commit so every environment runs the same Node 24.

Official sources

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: Node.js 20 to Node.js 24.

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 (Node.js 20 to Node.js 24) 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

Can I go straight from Node 20 to Node 24?

Yes. Go directly — there is no need to stop at Node 22 unless a critical dependency is not yet Node 24-ready. Bump your version pins, rebuild native modules across the ABI gap, and run the suite. Node 20 is end-of-life, so this is a security upgrade.

What is most likely to break going from 20 to 24?

Stale native addons (rebuild them first), the url.parse() runtime deprecation (move to new URL()), the removal of tls.createSecurePair, and — on Windows — the switch from MSVC to ClangCL for building from source. Application code is largely unaffected.