upgrade-node

Upgrade Node.js

When to use

• The user asks to upgrade Node, or the project runs an EOL line (20 or older, or 25/23/21) — see legacy/node-legacy.
• Node 22 is in use and the user wants to move before its EOL on 30 Apr 2027.
• A dependency now requires a newer Node.

For a minor or patch update on a supported line, update the pins (step 3) and run Verify.

Before you start

• List every place that pins Node, and note mismatches: .nvmrc, .node-version, .tool-versions, volta, engines.node, packageManager, Dockerfiles (FROM node:…), CI (node-version:, matrices), serverless and PaaS runtimes (runtime: nodejs20.x, vercel.json, buildpacks), and @types/node.
• List native and toolchain-sensitive dependencies: bcrypt, sharp, canvas, sqlite3/better-sqlite3, node-sass, grpc, anything with binding.gyp or node-gyp/prebuild in its install scripts (npm ls --all | grep -E "gyp|prebuild").
• Working tree clean; new branch (chore/node-26).
• Ask the user:
  • the target: Node 26 (Active LTS since 28 Oct 2026, EOL 30 Apr 2029; longest runway) or Node 24 (Maintenance LTS, EOL 30 Apr 2028; more conservative). Default to 26 for apps, and for libraries keep engines as wide as the supported lines (>=22);
  • where it runs (containers, serverless, PaaS) and whether that platform offers the target runtime yet;
  • whether network installs are approved (core/supply-chain cooldown applies).

Steps

1. Baseline on the current version: clean install, lint, typecheck, tests, build, and start the production image. Record failures; don't blame them on the upgrade later.
2. Plan the hop. Go straight to the target when tests are good and there are no unmaintained native modules. From 18 or older with native modules or old toolchains (Webpack 4, node-sass, Jest < 29), hop one LTS at a time (18 → 20 → 22 → 24/26) and fix each hop.
3. Update all pins in one change:
   • .nvmrc / .node-version / .tool-versions → the exact target (for example 26.13.0);
   • engines.node → >=26 for apps (or the supported range for libraries);
   • @types/node → the target major (npm install -D @types/node@26);
   • Dockerfiles → node:26-slim@sha256:<digest> (look up the real digest; see devops/docker);
   • CI → node-version-file: .nvmrc or the matrix of supported lines;
   • deploy runtimes → the platform's matching runtime identifier.
4. Reinstall and rebuild: delete node_modules, run the clean install, and run npm rebuild for native modules. Update native packages that have no prebuilt binaries for the new ABI to versions that do; replace unmaintained ones (node-sass → sass).
5. Fix API changes. Run the tests and read deprecation warnings (node --trace-deprecation). The Node.js userland migrations project publishes codemods for common removals; review their diffs. Typical items: removed or runtime-deprecated util.is*, url.parse() → new URL(), Buffer() constructor → Buffer.from/alloc, fs.rmdir(…, { recursive }) → fs.rm, crypto defaults, and stricter TLS (old ciphers and certificates rejected).
6. Tooling: update the test runner, bundler and TypeScript if they don't support the new Node (Vitest 5 and Jest 30 support current LTS lines), and the package manager (corepack or the pinned packageManager version).
7. Verify (next section), show the diff and results, and wait for approval; commit only when asked (git-commit skill). Then use languages/javascript-node.