Guía de Migración a Node.js 26 LTS: Pasá de 22 o 24 sin Sorpresas

node-pins.mjs (Node 18+, solo lectura)

// node-pins.mjs: lista cada lugar donde un repo fija una versión de Node.js (solo lectura).
// Correlo desde la raíz del repo con el Node.js que tenés hoy (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()}`);

// [qué archivos, qué líneas dentro de ellos]
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.");

Su salida en un repo de prueba que armé con versiones fijadas (recortada)

$ 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: elegí tu gestor de versiones y después fijá el proyecto

# nvm (macOS, Linux, WSL): instalá 26 y copiá tus paquetes globales de npm desde 24
nvm install --reinstall-packages-from=24 26
nvm alias default 26

# fnm (también en Windows)
fnm install 26
fnm default 26

# mise: escribe node = "26" en el mise.toml del proyecto
mise use node@26

# Volta: escribe volta.node en package.json (su README dice que ya no se mantiene)
volta pin node@26

# Después fijá el proyecto para el resto de las herramientas y revisá qué quedó
echo "26" > .nvmrc
npm pkg set engines.node="26.x"
npm install -g corepack            # solo si usás pnpm o Yarn 4: Node 25+ lo dejó de incluir
node -p "process.version + ' ' + process.release.lts"   # v26.13.0 Lithium

CI: sumá 26 a la matriz antes de cambiar producción

# .github/workflows/node-26.yml: la misma suite en cada línea con soporte
name: node-26
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false        # ver el resultado de cada línea, no solo la primera falla
      matrix:
        node: [22, 24, 26]    # 20 ya no tiene soporte: sacalo
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci
      - run: npm test
        env:
          # Solo en 26: cada deprecación en runtime pasa a ser un crash
          NODE_OPTIONS: ${{ matrix.node == 26 && '--throw-deprecation' || '' }}

Docker: cambiá una variable a la vez

# Antes: FROM node:24-bookworm-slim, o node:lts-slim (26 sobre Debian trixie desde el 28 oct)
# 1. Cambiá una cosa a la vez: misma versión de Debian, nuevo major de Node
FROM node:26.13.0-bookworm-slim
# 2. En otro PR, mové también el sistema operativo:  FROM node:26.13.0-trixie-slim
#    Fijá también el digest: docker buildx imagetools inspect node:26.13.0-bookworm-slim

# Las imágenes de Node 26 ya no traen Yarn v1. Elegí UNA de estas si necesitás un gestor:
RUN npm install --global yarn@1.22.22
# RUN npm install --global corepack@0.36.0 && corepack enable   # pnpm / Yarn 4

# Que el build falle temprano si la base no es la que pensás
RUN node -p "process.version + ' ' + process.release.lts"

Pasada estática: buscá en tu código y en tus dependencias

# 1. APIs eliminadas en 25 y 26 (git grep solo busca en archivos versionados)
git grep -nE "_stream_(readable|writable|duplex|transform|passthrough|wrap)|\.writeHeader\(|\bSlowBuffer\b|fs\.[FRWX]_OK\b|rmdir(Sync)?\(.*recursive|experimental-transform-types"

# 2. Deprecadas en runtime en 26: un warning hoy, un error en un major futuro
git grep -nE "module\.register\(|\{[^}]*\bregister\b[^}]*\} from ['\"](node:)?module|Duplex\.toWeb\("

# 3. El cambio de streams: revisá cada read() sin argumentos sobre un Readable
git grep -nE "\.read\(\)" -- "*.js" "*.mjs" "*.cjs" "*.ts"

# 4. Dependencias: una rotura conocida y addons nativos para recompilar en 26
npm ls yargs                     # necesita 16.2.2+, 17.7.3+ o 18
find node_modules -name "*.node" -not -path "*/test/*"

Antes y después (los tres fixes probados en 26.13.0)

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

// Antes: un read() por evento 'readable'. En 26 recibe UN buffer y puede quedar colgado
stream.on("readable", () => {
  const chunk = stream.read();
  if (chunk) handle(chunk);
});

// Fix 1: vaciá el buffer en cada evento (el patrón que usa la documentación de streams)
stream.on("readable", () => {
  let chunk;
  while ((chunk = stream.read()) !== null) handle(chunk);
});

// Fix 2: pedí todo lo que hay en el buffer, como sugiere el PR para el comportamiento viejo
const all = stream.read(stream.readableLength);

// Fix 3: for await ahora entrega un chunk por push(); juntalo si necesitás el body completo
const body = await text(stream);   // también buffer(), json(), arrayBuffer()

Recetas que aplican camino a 26

# Codemods oficiales de Node.js (nodejs/userland-migrations). Hacé commit antes: reescriben archivos.
npx codemod @nodejs/v22-to-v24                                # si venís de 22
npx codemod @nodejs/slow-buffer-to-buffer-alloc-unsafe-slow   # DEP0030, eliminada en 25
npx codemod @nodejs/fs-access-mode-constants                  # DEP0176, eliminada en 25
npx codemod @nodejs/rmdir                                     # DEP0147, eliminada en 25

Temporal sin flag y sin polyfill (temporal.mjs)

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

// 1. Una fecha de calendario: sin hora, sin zona horaria, sin errores de un día a medianoche UTC
const due = Temporal.PlainDate.from("2027-04-30");            // fin de vida de Node.js 22
const today = Temporal.Now.plainDateISO("UTC");
console.log("days left on Node 22:", today.until(due, { largestUnit: "day" }).days);
// 178 cuando lo corrí el 3 nov 2026

// 2. La aritmética de meses se ajusta en vez de desbordarse a marzo como Date
console.log(Temporal.PlainDate.from("2026-01-31").add({ months: 1 }).toString());
// 2026-02-28

// 3. Una reunión en una zona horaria, mostrada en otra
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. Respeta el horario de verano: +1 día mantiene la hora de reloj, +24 horas no
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: entra un Date legado, sale Temporal, y vuelta
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 e iterator sequencing

// Upsert: se terminó el "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 solo ejecuta el callback cuando la clave no está
const cache = new Map();
const slow = (k) => { console.log("computing", k); return k.length; };
cache.getOrInsertComputed("lithium", slow); // imprime "computing lithium"
cache.getOrInsertComputed("lithium", slow); // en caché: no imprime nada
console.log(cache.get("lithium"));          // 7

// Iterator sequencing: encadená iterables de forma lazy, sin volcarlos antes a arrays
const lines = Iterator.concat(["# header"], new Set(["a", "b"]), ["# footer"]);
console.log([...lines]); // [ '# header', 'a', 'b', '# footer' ]

Revisá el protocolo y desactivalo solo si hace falta

// check-h2.mjs: ¿qué protocolo negocia fetch()?
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 en 26.13.0 (undici 8.12.2), http/1.1 en 22.22.0 (undici 6.23.0)

// force-h1.mjs: volvé a HTTP/1.1 en todos los fetch() del proceso (npm i undici@8)
import { Agent, setGlobalDispatcher } from "undici";
setGlobalDispatcher(new Agent({ allowH2: false }));
// En Vercel Functions: en cambio, configurá VERCEL_FETCH_DISABLE_H2=1 y volvé a desplegar