Node.js 26 LTS Migration Guide: Move From 22 or 24 Without Surprises

node-pins.mjs (Node 18+, read-only)

// node-pins.mjs: list every place a repo pins a Node.js version (read-only).
// Run it from the repo root with the Node.js you have today (18+): node node-pins.mjs
import { execFileSync } from "node:child_process";
import { readFileSync } from "node:fs";
import { basename } from "node:path";

const files = execFileSync("git", ["ls-files"], { encoding: "utf8" }).split("\n").filter(Boolean);
const hits = [];
const add = (file, where, text) => hits.push(`${file}:${where}  ${text.trim()}`);

// [which files, which lines inside them]
const RULES = [
  [/(^|\/)(\.tool-versions|\.?mise\.toml)$/, /^\s*node(js)?\b/],
  [/(^|\/)(Dockerfile[^/]*|[^/]*\.dockerfile|(docker-)?compose[^/]*\.ya?ml)$/i, /\bnode:[\w.-]+/],
  [/\.(ya?ml|toml|json|tf)$/, /node-version|NODE_VERSION|nodejs\d+\.x|\bnode:\s*\[|image:\s*["']?node:/],
];

for (const file of files) {
  const name = basename(file);
  if (file.includes("node_modules/") || name === "package-lock.json") continue;
  let text;
  try { text = readFileSync(file, "utf8"); } catch { continue; }

  if (name === ".nvmrc" || name === ".node-version") { add(file, 1, text.split(/\r?\n/)[0]); continue; }

  if (name === "package.json") {
    let pkg;
    try { pkg = JSON.parse(text); } catch { continue; }
    if (pkg.engines?.node) add(file, "engines.node", pkg.engines.node);
    if (pkg.volta?.node) add(file, "volta.node", pkg.volta.node);
    const rt = [pkg.devEngines?.runtime].flat().find((r) => r?.name === "node");
    if (rt) add(file, "devEngines.runtime", rt.version ?? "(any)");
    continue;
  }

  const rule = RULES.find(([fileRe]) => fileRe.test(file));
  if (!rule) continue;
  text.split(/\r?\n/).forEach((line, i) => rule[1].test(line) && add(file, i + 1, line));
}

console.log(hits.length ? hits.join("\n") : "No Node.js pins found in tracked files.");

Its output on a test repo I seeded with pins (trimmed)

$ node node-pins.mjs
.github/workflows/ci.yml:5  node: [20, 22, 24]
.github/workflows/ci.yml:9  node-version: ${{ matrix.node }}
.gitlab-ci.yml:1  image: node:22
.nvmrc:1  24
Dockerfile:1  FROM node:lts-slim AS build
Dockerfile:3  FROM node:24-alpine
api/Dockerfile.dev:1  FROM --platform=linux/amd64 node:20.20.2-bookworm
api/package.json:engines.node  22.x
compose.yaml:3  image: node:24-bookworm-slim
mise.toml:2  node = "24"
netlify.toml:2  NODE_VERSION = "24"
package.json:engines.node  >=20
package.json:volta.node  24.22.1
serverless.yml:3  runtime: nodejs20.x
web/.node-version:1  v22.20.0

Local: pick your version manager, then pin the project

# nvm (macOS, Linux, WSL): install 26 and copy your global npm packages from 24
nvm install --reinstall-packages-from=24 26
nvm alias default 26

# fnm (Windows too)
fnm install 26
fnm default 26

# mise: writes node = "26" to the project's mise.toml
mise use node@26

# Volta: writes volta.node to package.json (its README says Volta is unmaintained)
volta pin node@26

# Then pin the project for every other tool, and check what you got
echo "26" > .nvmrc
npm pkg set engines.node="26.x"
npm install -g corepack            # only if you use pnpm or Yarn 4: Node 25+ dropped it
node -p "process.version + ' ' + process.release.lts"   # v26.13.0 Lithium

CI: add 26 to the matrix before you switch production

# .github/workflows/node-26.yml: the same suite on every supported line
name: node-26
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false        # see every line's result, not just the first failure
      matrix:
        node: [22, 24, 26]    # 20 is end-of-life: drop it
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci
      - run: npm test
        env:
          # On 26 only: every runtime deprecation becomes a crash
          NODE_OPTIONS: ${{ matrix.node == 26 && '--throw-deprecation' || '' }}

Docker: change one variable at a time

# Before: FROM node:24-bookworm-slim, or node:lts-slim (26 on Debian trixie since 28 Oct)
# 1. Change one thing at a time: same Debian release, new Node major
FROM node:26.13.0-bookworm-slim
# 2. In a separate PR, move the OS too:  FROM node:26.13.0-trixie-slim
#    Pin the digest as well: docker buildx imagetools inspect node:26.13.0-bookworm-slim

# Node 26 images no longer ship Yarn v1. Pick ONE of these if you need a package manager:
RUN npm install --global yarn@1.22.22
# RUN npm install --global corepack@0.36.0 && corepack enable   # pnpm / Yarn 4

# Fail the build early if the base is not what you think
RUN node -p "process.version + ' ' + process.release.lts"

Static pass: search your code and your dependencies

# 1. APIs removed in 25 and 26 (git grep only searches tracked files)
git grep -nE "_stream_(readable|writable|duplex|transform|passthrough|wrap)|\.writeHeader\(|\bSlowBuffer\b|fs\.[FRWX]_OK\b|rmdir(Sync)?\(.*recursive|experimental-transform-types"

# 2. Runtime-deprecated in 26: a warning today, an error in a later major
git grep -nE "module\.register\(|\{[^}]*\bregister\b[^}]*\} from ['\"](node:)?module|Duplex\.toWeb\("

# 3. The stream change: review every bare read() on a Readable
git grep -nE "\.read\(\)" -- "*.js" "*.mjs" "*.cjs" "*.ts"

# 4. Dependencies: a known breakage, and native addons to rebuild on 26
npm ls yargs                     # needs 16.2.2+, 17.7.3+ or 18
find node_modules -name "*.node" -not -path "*/test/*"

Before and after (the three fixes tested on 26.13.0)

import { text } from "node:stream/consumers";

// Before: one read() per 'readable' event. On 26 it gets ONE buffer and can stall forever
stream.on("readable", () => {
  const chunk = stream.read();
  if (chunk) handle(chunk);
});

// Fix 1: drain the buffer on every event (the pattern the stream docs use)
stream.on("readable", () => {
  let chunk;
  while ((chunk = stream.read()) !== null) handle(chunk);
});

// Fix 2: ask for everything buffered, as the PR suggests for the old behavior
const all = stream.read(stream.readableLength);

// Fix 3: for await now yields one chunk per push(); collect when you need the whole body
const body = await text(stream);   // also buffer(), json(), arrayBuffer()

Recipes that apply on the way to 26

# Official Node.js codemods (nodejs/userland-migrations). Commit first: they rewrite files.
npx codemod @nodejs/v22-to-v24                                # coming from 22
npx codemod @nodejs/slow-buffer-to-buffer-alloc-unsafe-slow   # DEP0030, removed in 25
npx codemod @nodejs/fs-access-mode-constants                  # DEP0176, removed in 25
npx codemod @nodejs/rmdir                                     # DEP0147, removed in 25

Temporal with no flag and no polyfill (temporal.mjs)

// temporal.mjs: node temporal.mjs on Node.js 26 (no flag, no polyfill)
if (typeof Temporal === "undefined") {
  throw new Error(`Temporal is not available on ${process.version}: use Node.js 26+`);
}

// 1. A calendar date: no time, no time zone, no off-by-one at midnight UTC
const due = Temporal.PlainDate.from("2027-04-30");            // Node.js 22 end-of-life
const today = Temporal.Now.plainDateISO("UTC");
console.log("days left on Node 22:", today.until(due, { largestUnit: "day" }).days);
// 178 when I ran it on 3 Nov 2026

// 2. Month arithmetic clamps instead of overflowing into March like Date does
console.log(Temporal.PlainDate.from("2026-01-31").add({ months: 1 }).toString());
// 2026-02-28

// 3. A meeting in one time zone, shown in another
const call = Temporal.ZonedDateTime.from("2026-11-10T09:00[America/Montevideo]");
console.log(call.withTimeZone("Europe/Madrid").toString());
// 2026-11-10T13:00:00+01:00[Europe/Madrid]

// 4. DST-aware: +1 day keeps the wall-clock time, +24 hours doesn't
const beforeDst = Temporal.ZonedDateTime.from("2027-03-27T12:00[Europe/Madrid]");
console.log(beforeDst.add({ days: 1 }).toString());    // 2027-03-28T12:00:00+02:00[Europe/Madrid]
console.log(beforeDst.add({ hours: 24 }).toString());  // 2027-03-28T13:00:00+02:00[Europe/Madrid]

// 5. Interop: a legacy Date in, Temporal out, and back
const instant = new Date("2026-10-28T16:57:41Z").toTemporalInstant();
console.log(instant.toZonedDateTimeISO("UTC").toPlainDate().toString()); // 2026-10-28
console.log(new Date(instant.epochMilliseconds).toISOString());          // 2026-10-28T16:57:41.000Z

V8 14.6: upsert and iterator sequencing

// Upsert: no more "if (!map.has(k)) map.set(k, [])"
const byStatus = new Map();
for (const [status, url] of [[200, "/a"], [404, "/b"], [200, "/c"]]) {
  byStatus.getOrInsert(status, []).push(url);
}
console.log(byStatus); // Map(2) { 200 => [ '/a', '/c' ], 404 => [ '/b' ] }

// getOrInsertComputed only runs the callback on a miss
const cache = new Map();
const slow = (k) => { console.log("computing", k); return k.length; };
cache.getOrInsertComputed("lithium", slow); // logs "computing lithium"
cache.getOrInsertComputed("lithium", slow); // cached: no log
console.log(cache.get("lithium"));          // 7

// Iterator sequencing: chain iterables lazily, without spreading them into arrays first
const lines = Iterator.concat(["# header"], new Set(["a", "b"]), ["# footer"]);
console.log([...lines]); // [ '# header', 'a', 'b', '# footer' ]

Check the protocol, and opt out only if you must

// check-h2.mjs: which protocol does fetch() negotiate?
import dc from "node:diagnostics_channel";
dc.subscribe("undici:client:connected", ({ socket }) => console.log(socket.alpnProtocol));
await fetch("https://www.cloudflare.com/", { method: "HEAD" });
// h2 on 26.13.0 (undici 8.12.2), http/1.1 on 22.22.0 (undici 6.23.0)

// force-h1.mjs: back to HTTP/1.1 for every fetch() in the process (npm i undici@8)
import { Agent, setGlobalDispatcher } from "undici";
setGlobalDispatcher(new Agent({ allowH2: false }));
// On Vercel Functions: set VERCEL_FETCH_DISABLE_H2=1 and redeploy instead