Pular para o conteúdo
< samuelsantana.dev />
Voltar para o Blogread() em laço sobre a, b e c: um pedaço ["abc"] no Node 24.19.0, três pedaços ["a","b","c"] no Node 26.13.0.

Node 24 para 26 numa API NestJS: o que muda de verdade

Samuel Santana
Publicado em 30 de outubro de 2026
NodeJSNestJSAmazon Web Services

Troquei o Node 24 pelo 26.13.0 nas duas APIs NestJS que eu mantenho em produção, a deste blog (vertex-api) e a do Pyxis (pyxis-api), e rodei tudo o que elas têm de teste. Passou tudo, sem mudar uma linha: 248 testes unitários e 65 de ponta a ponta numa; 2.600 unitários, 373 de integração e 228 de ponta a ponta na outra. As duas sobem, respondem no /health e não imprimem nenhum aviso de depreciação, nem com --pending-deprecation.

Nenhuma das duas vai para o Node 26 esta semana. As duas rodam no AWS Lambda, e o runtime nodejs26.x ainda é preview, que a própria AWS manda não usar em produção.

E a suíte verde prova menos do que parece. Entre o 24 e o 26, o read() de um Readable passou a devolver outra coisa e o fetch passou a falar outro protocolo. Nenhum teste meu cobre isso porque nenhum código meu depende disso. O seu pode depender.

O que sai entre o 24 e o 26, e o que o 24 avisa antes

O changelog do 26.0.0, de 5 de maio de 2026, lista três remoções que aparecem em todo resumo: os módulos internos _stream_*, o writeHeader() da resposta HTTP e a flag --experimental-transform-types. Quem sai do 24 leva junto as remoções do 25.0.0, uma versão que quem só usa LTS nunca rodou. Rodei cada item no 24.19.0 para ver se ele avisa antes de quebrar:

O que saiCódigoRemovido noO Node 24 avisa ao rodar?
require('_stream_readable') e os outros _stream_*DEP019326não (só o _stream_wrap, pelo DEP0125)
res.writeHeader()DEP006326não, nem com --pending-deprecation
--experimental-transform-typesflag26não
SlowBufferDEP003025só quando alguém chama SlowBuffer()
fs.F_OK, fs.R_OK, fs.W_OK, fs.X_OKDEP017625sim
fs.rmdir(caminho, { recursive: true })DEP014725sim
Corepack junto com o Node25não se aplica

A lista inteira está na página Deprecated APIs. Ela diz que o DEP0193 virou aviso em tempo de execução no 24.2.0, mas no 24.19.0 o require('_stream_readable') carrega em silêncio, e a mesma página na documentação do 24.19.0 marca o item como só de documentação. Eu confiaria no que o processo imprime, não na tabela.

No 26, os dois primeiros falham assim:

$ node -e "require('_stream_readable')"
Error: Cannot find module '_stream_readable'
  code: 'MODULE_NOT_FOUND',

$ node --experimental-transform-types -e "1"
...\node.exe: bad option: --experimental-transform-types

E um servidor HTTP que chama res.writeHeader(200) responde normalmente no 24, sem aviso nenhum, e no 26 lança TypeError: res.writeHeader is not a function na primeira requisição. O da flag é o mais traiçoeiro, porque não quebra uma rota: impede o processo de subir. Numa API NestJS ela dificilmente está no código da aplicação (o TypeScript nativo do Node não transforma decorators, então um app Nest nunca rodou por ele), mas pode estar num NODE_OPTIONS, no CMD de um Dockerfile ou num script de CI.

Em TypeScript, parte disso o compilador já pega. O @types/node 24.13.2 do vertex-api não declara fs.F_OK nem writeHeader, e o 26.6.6 tira também o SlowBuffer. Compilei de propósito um arquivo que usa os três: o tsc com o @types/node 26 apontou os três, e os dois projetos compilaram limpos com ele. O que o compilador não lê é o JavaScript dentro de node_modules, e foi lá que apareceu o caso mais interessante.

O resto do 26.0.0 é acréscimo: Temporal global ligado por padrão, V8 14.6 (com Map.prototype.getOrInsert() e Iterator.concat()) e o undici 8 por trás do fetch. E um efeito do Web Storage, ligado desde o 25: no 26, sem --localstorage-file, ler typeof localStorage devolve "undefined" e imprime um ExperimentalWarning. Uma biblioteca que testa isso para saber se está no navegador vai pôr esse aviso no seu log.

O pacote que morre no require sem o 24 avisar

O @nestjs/jwt usa o jsonwebtoken, que usa o jws, que usa o jwa. Na versão 1.4.1 e na 2.0.0, a primeira linha do jwa carrega o buffer-equal-constant-time 1.0.1, e esse pacote lê SlowBuffer.prototype no topo do arquivo, no momento em que é carregado. Do 25 em diante, SlowBuffer é undefined.

Nos meus dois projetos isso não acontece: o vertex-api tem o jwa 2.0.1, e o pyxis-api nem usa jsonwebtoken. Para ver o erro, forcei a versão antiga num diretório separado:

{
  "name": "repro-jwa",
  "private": true,
  "dependencies": { "jsonwebtoken": "9.0.2" },
  "overrides": { "jwa": "1.4.1" }
}
$ node --trace-deprecation --pending-deprecation -e "require('jsonwebtoken'); console.log('ok')"   # v24.19.0
ok
$ node -e "require('jsonwebtoken')"   # v26.13.0
...\node_modules\buffer-equal-constant-time\index.js:37
var origSlowBufEqual = SlowBuffer.prototype.equal;
                                  ^

TypeError: Cannot read properties of undefined (reading 'prototype')
    at Object.<anonymous> (...\node_modules\buffer-equal-constant-time\index.js:37:35)
    ...
    at Object.<anonymous> (...\node_modules\jwa\index.js:1:19)

O 24 fica quieto porque o aviso do DEP0030 sai quando alguém chama SlowBuffer(), e esse código só lê uma propriedade dele. O jwa 1.4.2 e o 2.0.1, publicados em 7 de maio de 2025, só carregam o buffer-equal-constant-time se crypto.timingSafeEqual não existir, o que não acontece em nenhum Node atual. Um lockfile que ninguém atualiza desde antes disso sobe no 24 e cai no primeiro require do 26, na hora do boot.

A correção cabe na faixa que o package.json já aceita (o jsonwebtoken 9.0.2 pede jws ^3.2.2, que pede jwa ^1.4.1):

npm ls jwa
npm update jwa

No diretório de teste, npm update jwa levou o pacote para o 1.4.2 e o mesmo require passou no 26.

read() agora devolve um pedaço de cada vez

Esta é a mudança de comportamento do 26.0.0 que menos aparece nos resumos (o commit se chama "stream: readable read one buffer at a time", nodejs/node#60441). Num Readable de bytes, sem setEncoding, read() sem argumento devolvia tudo o que estava no buffer interno, concatenado. No 26, devolve o próximo pedaço, do tamanho em que ele foi empurrado.

// readable-read.mjs: o que read() sem argumento devolve no Node 24 e no Node 26
import { Readable } from 'node:stream';

const r = new Readable({ read() {} });
r.push(Buffer.from('{"id":1,'));
r.push(Buffer.from('"ok":true}'));
r.push(null);

r.once('readable', () => {
  const chunk = r.read(); // sem tamanho: "me dá o que tiver no buffer"
  console.log(process.version, JSON.stringify(chunk.toString()));
  try {
    console.log('parsed:', JSON.parse(chunk));
  } catch (err) {
    console.log('JSON.parse failed:', err.message);
  }
});
$ node readable-read.mjs   # Node 24.19.0
v24.19.0 "{\"id\":1,\"ok\":true}"
parsed: { id: 1, ok: true }
$ node readable-read.mjs   # Node 26.13.0
v26.13.0 "{\"id\":1,"
JSON.parse failed: Expected double-quoted property name in JSON at position 8 (line 1 column 9)

O efeito aparece também longe do read() chamado à mão. Li os mesmos três pedaços (a, b e c, empurrados de uma vez) de seis jeitos:

Como lêNode 24.19.0Node 26.13.0
read() em laço até null["abc"]["a","b","c"]
for await (const chunk of stream)["abc"]["a","b","c"]
stream.toArray()["abc"]["a","b","c"]
evento 'data'["a","b","c"]["a","b","c"]
text() de node:stream/consumers"abc""abc"
read() em laço, com setEncoding('utf8')["abc"]["abc"]

O caminho novo só vale quando o stream não tem decoder, por isso o setEncoding mantém o comportamento antigo. Código que montava uma mensagem com um único read(), ou que tratava cada volta do for await como uma unidade, passa a receber a mensagem em partes. Num socket de verdade esse código já estava errado, porque a rede nunca prometeu fronteira de pedaço; o 26 só torna o erro determinístico.

A documentação do readable.read() da própria versão 26.13.0 ainda diz que, sem o argumento, o método devolve todo o conteúdo do buffer interno. O script acima mostra outra coisa. A descrição do PR sugere readable.read(readable.readableLength) para chegar perto do comportamento antigo; quando a intenção é ler tudo, eu prefiro sair do read() manual e usar text(), json() ou buffer() de node:stream/consumers, que deram o mesmo resultado nas duas versões.

Nos dois projetos, o único lugar que lê um stream desse jeito é a exportação de CSV do pyxis-api: um for await sobre a saída do gzip, que junta os pedaços com Buffer.concat e não depende de onde cada um termina.

O fetch passa a negociar HTTP/2

O undici 8, que está por trás do fetch global no Node 26 (8.12.2 no 26.13.0; o 24.19.0 traz o 7.29.0), liga o HTTP/2 por padrão (nodejs/undici#4828). Se o servidor oferece h2 na negociação TLS, o fetch usa. Um servidor local que aceita os dois protocolos mostra a diferença:

# Certificado autoassinado, só para o teste. No Git Bash do Windows, prefixe com MSYS_NO_PATHCONV=1.
openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 2 -subj "/CN=localhost" -addext "subjectAltName=DNS:localhost"
// fetch-protocol.mjs: com que versão de HTTP o fetch() global chega a um servidor que aceita as duas
import { createSecureServer } from 'node:http2';
import { readFileSync } from 'node:fs';

const server = createSecureServer({
  key: readFileSync(new URL('key.pem', import.meta.url)),
  cert: readFileSync(new URL('cert.pem', import.meta.url)),
  allowHTTP1: true, // aceita HTTP/1.1 e HTTP/2; quem escolhe, via ALPN, é o cliente
});
server.on('request', (req, res) => res.end(`httpVersion=${req.httpVersion}`));
await new Promise((resolve) => server.listen(0, resolve));

process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'; // certificado autoassinado, só neste teste local
const res = await fetch(`https://localhost:${server.address().port}/`);
console.log(process.version, `undici ${process.versions.undici}`, await res.text());
process.exit(0);
$ node fetch-protocol.mjs   # Node 24.19.0
...
v24.19.0 undici 7.29.0 httpVersion=1.1
$ node fetch-protocol.mjs   # Node 26.13.0
...
v26.13.0 undici 8.12.2 httpVersion=2.0

(O ... corta o aviso que o Node imprime por causa do NODE_TLS_REJECT_UNAUTHORIZED.)

Os dois projetos usam fetch para mandar e-mail pela API do Resend, e api.resend.com oferece h2 na negociação (conferi com openssl s_client -alpn h2,http/1.1). No 26, esse tráfego troca de protocolo sem nenhuma linha de código mudar. Não mandei e-mail nenhum no teste: o que eu medi foi o fetch, não o Resend. A página de globals da documentação do 26.13.0, aliás, ainda apresenta o undici como um cliente HTTP/1.1.

HTTP/2 por padrão muda também o jeito como as falhas aparecem. Montei um teste mínimo: o primeiro fetch para a origem leva um cabeçalho que o undici recusa nas duas versões (upgrade), e depois vêm dois pedidos normais.

// fetch-h2-hang.mjs: o primeiro fetch para a origem é recusado pelo undici; e os próximos?
import { createSecureServer } from 'node:http2';
import { readFileSync } from 'node:fs';

const server = createSecureServer({
  key: readFileSync(new URL('key.pem', import.meta.url)),
  cert: readFileSync(new URL('cert.pem', import.meta.url)),
  allowHTTP1: true,
});
server.on('request', (req, res) => res.end(`httpVersion=${req.httpVersion}`));
await new Promise((resolve) => server.listen(0, resolve));
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
const url = `https://localhost:${server.address().port}/`;

// 'upgrade' é um cabeçalho que o undici recusa no fetch, nas duas versões.
for (const headers of [{ upgrade: 'websocket' }, {}, {}]) {
  const started = performance.now();
  try {
    const res = await fetch(url, { headers, signal: AbortSignal.timeout(3000) });
    console.log(process.version, JSON.stringify(headers), res.status, await res.text());
  } catch (err) {
    const ms = Math.round(performance.now() - started);
    console.log(process.version, JSON.stringify(headers), err.cause?.code ?? err.name, `${ms} ms`);
  }
}
process.exit(0);
$ node fetch-h2-hang.mjs   # Node 24.19.0
v24.19.0 {"upgrade":"websocket"} UND_ERR_INVALID_ARG 15 ms
...
v24.19.0 {} 200 httpVersion=1.1
v24.19.0 {} 200 httpVersion=1.1
$ node fetch-h2-hang.mjs   # Node 26.13.0
v26.13.0 {"upgrade":"websocket"} UND_ERR_INVALID_ARG 17 ms
v26.13.0 {} TimeoutError 3004 ms
v26.13.0 {} TimeoutError 3005 ms

No 26, os pedidos seguintes para a mesma origem ficam parados até o AbortSignal.timeout cortar, e o aviso do NODE_TLS_REJECT_UNAUTHORIZED nem chega a sair: nenhuma conexão TLS foi aberta. Repeti várias vezes e o resultado não mudou. Com um pedido bem-sucedido antes, uma recusa sozinha não travou nada, mas duas recusas seguidas travaram o pedido seguinte. Um jeito plausível de cair nisso é uma rota que repassa para um fetch os cabeçalhos da requisição que recebeu. Não sei se é o mesmo defeito de duas issues abertas no undici sobre sessões HTTP/2 que não se recuperam (#6073 e #6106, ambas de outubro de 2026); mostro porque é um tipo de falha que o mesmo código não tinha no 24.

A saída documentada para voltar ao HTTP/1.1 é instalar o pacote undici e trocar o dispatcher global, como a página de globals do Node descreve. Com estas linhas no topo do mesmo script, os dois pedidos depois da recusa voltaram a responder:

+// Requer o pacote undici na versão que o Node traz: npm install undici@8.12.2
+import { Agent, setGlobalDispatcher } from 'undici';
 import { createSecureServer } from 'node:http2';
 import { readFileSync } from 'node:fs';

+setGlobalDispatcher(new Agent({ allowH2: false }));
$ node fetch-h2-off.mjs   # Node 26.13.0
v26.13.0 {"upgrade":"websocket"} UND_ERR_INVALID_ARG 100 ms
...
v26.13.0 {} 200 httpVersion=1.1
v26.13.0 {} 200 httpVersion=1.1

Eu não desligaria o HTTP/2 por reflexo. Mas num serviço que conversa por fetch com APIs de terceiros, ele é a mudança do 26 que eu mais vigiaria depois do deploy, e é a primeira coisa que eu testaria se aparecer um timeout novo.

Uma varredura para o que o 24 não avisa

Para os itens da tabela que o Node 24 não denuncia, escrevi um script que procura os padrões no projeto e em node_modules e diz em que pacote e versão cada ocorrência está. Não tem dependência e roda em qualquer Node a partir do 18:

#!/usr/bin/env node
// node26-scan.mjs: procura no projeto (código e node_modules) o que o Node 25 e o 26 removeram.
// Uso: node node26-scan.mjs [pasta-do-projeto]   (sem dependências; roda no Node 18 ou mais novo)
import { readdirSync, readFileSync, statSync } from 'node:fs';
import { join, relative, sep, basename } from 'node:path';

const root = process.argv[2] ?? process.cwd();

// Cada regra: o padrão, o código DEP da documentação do Node e o que acontece no 26.
const RULES = [
  { id: 'DEP0193', what: "require/import of 'node:_stream_*' (removed in 26)",
    re: /(?:require\s*\(\s*|from\s+|import\s*\(\s*)['"](?:node:)?_stream_(?:readable|writable|duplex|transform|passthrough|wrap)['"]/ },
  { id: 'DEP0063', what: 'response.writeHeader() (removed in 26, use writeHead)',
    re: /\.writeHeader\s*\(/ },
  { id: 'flag', what: '--experimental-transform-types (flag removed in 26)',
    re: /--experimental-transform-types/ },
  // Só acesso ao SlowBuffer do Node; polyfills de navegador que definem o próprio ficam de fora.
  { id: 'DEP0030', what: 'SlowBuffer (removed in 25)',
    re: /(?:require\(\s*['"](?:node:)?buffer['"]\s*\)|\bbuffer)\.SlowBuffer\b(?!\s*=[^=])|\bSlowBuffer\.prototype\b|new\s+SlowBuffer\s*\(|\{[^}]*\bSlowBuffer\b[^}]*\}\s*(?:=\s*require\(|from)\s*['"](?:node:)?buffer['"]/ },
  { id: 'DEP0176', what: 'fs.F_OK/R_OK/W_OK/X_OK (removed in 25, use fs.constants)',
    re: /\bfs\.(?:F_OK|R_OK|W_OK|X_OK)\b/ },
  { id: 'DEP0147', what: 'fs.rmdir with { recursive } (removed in 25, use fs.rm)',
    re: /\brmdir(?:Sync)?\s*\([^)]*recursive/ },
  { id: 'DEP0173', what: 'assert.CallTracker (removed in 25)',
    re: /\bCallTracker\b/ },
  { id: 'DEP0160', what: "process.on('multipleResolves') (removed in 25)",
    re: /['"]multipleResolves['"]/ },
  { id: 'DEP0205', what: 'module.register() (runtime warning in 26, use registerHooks)',
    re: /\bmodule\.register\s*\(\s*[^)\s]|\{\s*register\s*\}\s*(?:=\s*require\(|from\s+)\s*['"](?:node:)?module['"]/ },
  { id: 'corepack', what: 'corepack (no longer bundled with Node since 25)',
    re: /\bcorepack\s+(?:enable|prepare|use|install)\b/ },
];

const CODE = /\.(?:[cm]?js|[cm]?ts|jsx|tsx)$/;
const DECLARATION = /\.d\.[cm]?ts$/;
const CONFIG = /^(?:package\.json|Dockerfile.*|.*\.ya?ml|.*\.sh|\.npmrc)$/;
const SKIP_DIRS = new Set(['.git', 'coverage', '.cache', '.turbo', '.next']);
// Testes de pacotes instalados não rodam no seu app; os testes do seu projeto, sim.
const PACKAGE_TESTS = /node_modules.*[\\/](?:tests?|__tests__)[\\/]|node_modules.*[\\/](?:tests?|[^\\/]+\.(?:test|spec))\.[cm]?js$/;

// Para cada arquivo em node_modules, devolve "pacote@versão"; fora dele, "(project)".
const versions = new Map();
function packageOf(file) {
  const parts = relative(root, file).split(sep);
  const i = parts.lastIndexOf('node_modules');
  if (i < 0) return '(project)';
  const nameParts = parts[i + 1]?.startsWith('@') ? parts.slice(i + 1, i + 3) : parts.slice(i + 1, i + 2);
  const dir = join(root, ...parts.slice(0, i + 1), ...nameParts);
  if (!versions.has(dir)) {
    let version = '?';
    try { version = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version; } catch {}
    versions.set(dir, `${nameParts.join('/')}@${version}`);
  }
  return versions.get(dir);
}

const findings = [];
let scanned = 0;
function walk(dir) {
  let entries;
  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
  for (const entry of entries) {
    const full = join(dir, entry.name);
    if (entry.isSymbolicLink()) continue;
    if (entry.isDirectory()) {
      // @types/node só tem declarações: SlowBuffer aparece lá sem ser uso.
      if (!SKIP_DIRS.has(entry.name) && !(entry.name === 'node' && basename(dir) === '@types')) walk(full);
      continue;
    }
    const isCode = CODE.test(entry.name) && !DECLARATION.test(entry.name);
    if (!isCode && !CONFIG.test(entry.name)) continue;
    if (PACKAGE_TESTS.test(full)) continue;
    if (statSync(full).size > 5_000_000) continue;
    scanned++;
    readFileSync(full, 'utf8').split('\n').forEach((line, n) => {
      for (const rule of RULES) {
        const m = rule.re.exec(line);
        if (!m) continue;
        const start = Math.max(0, m.index - 40);
        findings.push({ rule, pkg: packageOf(full), where: `${relative(root, full)}:${n + 1}`,
          snippet: line.slice(start, m.index + m[0].length + 40).trim() });
      }
    });
  }
}

walk(root);

console.log(`${scanned} files read in ${root}`);
if (!findings.length) console.log('Nothing found.');
for (const rule of RULES) {
  const hits = findings.filter((f) => f.rule === rule);
  if (!hits.length) continue;
  console.log(`\n[${rule.id}] ${rule.what}: ${hits.length} hit(s)`);
  for (const h of hits) console.log(`  ${h.pkg}  ${h.where}\n    ${h.snippet}`);
}

No vertex-api, a saída inteira foi esta:

$ node node26-scan.mjs vertex-api
21143 files read in vertex-api

[flag] --experimental-transform-types (flag removed in 26): 2 hit(s)
  synckit@0.11.13  node_modules\synckit\lib\constants.js:23
    export const TRANSFORM_TYPES_FLAG = '--experimental-transform-types';
  synckit@0.11.13  node_modules\synckit\lib\index.cjs:72
    const TRANSFORM_TYPES_FLAG = "--experimental-transform-types";

[DEP0030] SlowBuffer (removed in 25): 6 hit(s)
  buffer-equal-constant-time@1.0.1  node_modules\buffer-equal-constant-time\index.js:4
    var SlowBuffer = require('buffer').SlowBuffer;
  buffer-equal-constant-time@1.0.1  node_modules\buffer-equal-constant-time\index.js:31
    Buffer.prototype.equal = SlowBuffer.prototype.equal = function equal(that) {
  buffer-equal-constant-time@1.0.1  node_modules\buffer-equal-constant-time\index.js:37
    var origSlowBufEqual = SlowBuffer.prototype.equal;
  buffer-equal-constant-time@1.0.1  node_modules\buffer-equal-constant-time\index.js:40
    SlowBuffer.prototype.equal = origSlowBufEqual;
  safe-buffer@5.2.1  node_modules\safe-buffer\index.js:64
    return buffer.SlowBuffer(size)
  safer-buffer@2.1.2  node_modules\safer-buffer\dangerous.js:54
    return buffer.SlowBuffer(size)

[DEP0147] fs.rmdir with { recursive } (removed in 25, use fs.rm): 3 hit(s)
  drizzle-kit@0.31.11  node_modules\drizzle-kit\bin.cjs:14350
    rue, force: true }) : await j3.promises.rmdir(this.oldCacheDirectory, { recursive: true }));
  tsx@4.23.0  node_modules\tsx\dist\index-D9F1FXzN.cjs:13
    ecursive:!0,force:!0}):await j.promises.rmdir(this.oldCacheDirectory,{recursive:!0}))}catch{}}}var z=process.env.TSX_DI
  tsx@4.23.0  node_modules\tsx\dist\index-XurvG3JN.mjs:13
    ecursive:!0,force:!0}):await j.promises.rmdir(this.oldCacheDirectory,{recursive:!0}))}catch{}}}var q=process.env.TSX_DI

Onze ocorrências, e nenhuma quebra o vertex-api no 26. Ler cada uma levou poucos minutos:

  • O synckit só usa a flag abaixo do Node 23.6; no 26 o código sai do switch antes de chegar nela.
  • No drizzle-kit e no tsx, o rmdir com recursive está no ramo de reserva de um fs.rm ? ... : ..., que só roda em Node sem fs.rm.
  • O safe-buffer 5.2.1 exporta o buffer nativo quando ele tem allocUnsafeSlow, então a função que chama SlowBuffer nunca é usada. O safer-buffer/dangerous.js não é importado por nenhum pacote da árvore.
  • O buffer-equal-constant-time é o pacote da seção anterior. Ele quebra se for carregado, e o jwa 2.0.1 deste projeto não o carrega.

No pyxis-api, a varredura achou as mesmas famílias, sem o buffer-equal-constant-time, e mais um import { register } from "node:module" no jiti 2.6.1, que chega pelo ESLint e pelo commitlint. Ele está no arquivo que só roda com --import jiti/register, e nada no projeto usa isso.

A varredura sozinha não separa o que é carregado do que só está instalado. Para isso, o segundo script importa cada dependência de produção do package.json no Node em que ele roda:

// load-deps.mjs: importa cada dependência de produção do package.json no Node atual.
// Salve na raiz do projeto e rode com o Node novo: node load-deps.mjs
// Pega o que quebra ao carregar o módulo, não o que só quebra quando uma função é chamada.
import { readFileSync } from 'node:fs';

const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));

let failed = 0;
for (const name of Object.keys(pkg.dependencies ?? {})) {
  try {
    await import(name);
    console.log(`ok    ${name}`);
  } catch (err) {
    failed++;
    console.log(`FAIL  ${name}: ${err.code ?? err.name}: ${err.message.split('\n')[0]}`);
  }
}
console.log(`${process.version}: ${failed} failed`);
process.exitCode = failed ? 1 : 0;

No diretório com o jwa antigo, ele pega o problema no 26 e não no 24:

$ node load-deps.mjs   # Node 24.19.0
ok    jsonwebtoken
v24.19.0: 0 failed
$ node load-deps.mjs   # Node 26.13.0
FAIL  jsonwebtoken: TypeError: Cannot read properties of undefined (reading 'prototype')
v26.13.0: 1 failed

No vertex-api e no pyxis-api, com o 26, as dependências de produção carregaram todas (0 failed).

O que os dois projetos disseram

Rodei tudo nos dois Nodes, com os bancos dos testes de integração e de ponta a ponta num Postgres descartável no Docker. As suítes com Jest rodaram com NODE_OPTIONS="--trace-deprecation --pending-deprecation":

vertex-api (NestJS 11, Fastify)pyxis-api (NestJS 12, Fastify)
Unitários248 de 248, nos dois2.600 de 2.600, nos dois
Integração com Postgres(não tem)373 de 373, nos dois
Ponta a ponta com Postgres65 de 65, nos dois228 de 228, nos dois
Lint e buildok nos doisok nos dois, mais typecheck e 33 testes de node --test
App subindo com os dois flags de depreciação0 avisos0 avisos
load-deps.mjs no 260 falhas0 falhas

O único addon nativo dos dois, o argon2 0.44.0 do vertex-api, carregou e gerou hash no 26 sem recompilar. O NODE_MODULE_VERSION mudou de 137 para 147, mas os binários que o pacote traz são N-API, que não dependem dele. Um addon compilado contra a ABI do Node, sem N-API, precisaria de npm rebuild ou de uma versão nova.

Os engines também não seguram ninguém: @nestjs/core 11 e 12 pedem >= 20, o postgres pede >=12, o Jest 30 aceita >=24.0.0, e o drizzle-orm e o fastify não declaram nada.

Tempo e memória

Medi com a máquina sem outros testes rodando (CPU entre 6% e 20% antes de começar), alternando 24 e 26 a cada execução. As suítes rodaram 5 vezes cada, depois de uma rodada de aquecimento descartada. O boot é o tempo entre criar o processo e o primeiro 200 em /health, em 7 execuções por Node. A memória foi lida dentro do processo (process.memoryUsage()) um segundo depois de pronto e de novo depois de 500 requisições ao /health. Os números são medianas, com mínimo e máximo entre parênteses:

Node 24.19.0Node 26.13.0Diferença
vertex-api, unitários3,60 s (3,57–4,76)3,27 s (3,19–3,52)−9%
vertex-api, ponta a ponta4,63 s (4,58–4,99)4,03 s (3,97–4,15)−13%
pyxis-api, unitários19,8 s (19,7–21,9)18,3 s (18,1–18,6)−7%
vertex-api, até responder /health703 ms (694–764)575 ms (569–594)−18%
pyxis-api, até responder /health1.112 ms (1.097–1.247)925 ms (917–1.072)−17%
vertex-api, RSS em repouso137 MiB (137–139)132 MiB (117–133)−4%
pyxis-api, RSS em repouso241 MiB (214–242)182 MiB (180–184)−24%
vertex-api, heap usado depois de 500 requisições55,5 MiB (55,3–57,8)62,5 MiB (58,4–62,6)+13%
pyxis-api, heap usado depois de 500 requisições81,9 MiB (70,0–98,3)76,4 MiB (55,4–82,2)−7%

O 26 foi mais rápido em todas as medianas de tempo, e as faixas de mínimo e máximo dos dois não se cruzam em nenhuma linha de tempo. Na memória, o RSS caiu nos dois projetos, mas o heap depois das requisições subiu num e caiu no outro. Com essa dispersão, eu não tiraria conclusão sobre heap. Isso é um notebook com Windows (i9-13900H) e um processo de vida longa, não um cold start no Lambda, que tem CPU e disco de outro tamanho. O ganho no boot é o número que eu mais queria medir no runtime gerenciado, e ainda não deu.

No Lambda, o 26 ainda é preview

As duas APIs rodam no Lambda como imagem de contêiner, e as duas imagens partem de public.ecr.aws/lambda/nodejs:24. É aqui que a data de LTS do Node e a data de produção se separam.

A AWS anunciou o nodejs26.x em preview público em agosto de 2026 (anúncio e post no blog de Compute), tanto como runtime gerenciado quanto como imagem base com a tag 26-preview. A página de runtimes diz com todas as letras que preview não tem SLA nem suporte e não deve ser usado em produção, e indica novembro de 2026 como mês-alvo do lançamento, com a ressalva de que a data é indicativa. O post da AWS amarra o lançamento ao Node 26 virar Active LTS, o que aconteceu em 28 de outubro, e mira um prazo de até dois meses depois disso.

Há um detalhe do Lambda que um guia genérico de upgrade não cobre. O runtime do Lambda desliga recursos experimentais do Node com flags próprios: no 20, 22 e 24, ele passa --no-experimental-require-module, e quem quer require() de ES modules precisa religar com NODE_OPTIONS=--experimental-require-module. O Dockerfile.lambda do pyxis-api faz exatamente isso. A tabela da documentação ainda não lista o 26, e na issue de feedback do preview (aws-lambda-nodejs-runtime-interface-client#198) há relatos de usuários de que o require(esm) continua desligado e de que o Temporal não aparece no nodejs26.x.

Fui conferir na imagem 26-preview publicada em 30 de outubro (26-preview.2026.10.30.17-x86_64), com uma função que só devolve o que vê, invocada pelo emulador que vem dentro da imagem:

// index.js: o que o runtime nodejs26.x (preview) mostra para uma função
exports.handler = async () => {
  let requireEsm;
  try {
    requireEsm = require('./esm-dep.mjs').kind;
  } catch (err) {
    requireEsm = `${err.code}: ${err.message.split('\n')[0]}`;
  }
  return {
    version: process.version,
    temporal: typeof Temporal,
    requireModuleFeature: process.features.require_module,
    execArgv: process.execArgv,
    nodeOptions: process.env.NODE_OPTIONS ?? null,
    requireEsm,
  };
};
== NODE_OPTIONS=''
{"version":"v26.13.0","temporal":"undefined","requireModuleFeature":false,
 "execArgv":["--expose-gc","--max-http-header-size","81920","--no-experimental-detect-module",
 "--no-experimental-require-module","--no-experimental-ffi","--max-semi-space-size=50","--max-old-space-size=2708"],
 "nodeOptions":null,
 "requireEsm":"ERR_REQUIRE_ESM: require() of ES Module /var/task/esm-dep.mjs from /var/task/index.js not supported."}
== NODE_OPTIONS=--experimental-require-module
{"version":"v26.13.0","temporal":"undefined","requireModuleFeature":true, ... "requireEsm":"esm"}

O esm-dep.mjs é uma linha, export const kind = 'esm';, e a saída foi quebrada em linhas aqui para caber. Os dois relatos se confirmam, por motivos diferentes. O require(esm) está desligado pelo flag que o runtime passa, e o mesmo NODE_OPTIONS de antes o religa. O Temporal não volta com flag nenhum: rodando o node da imagem direto, fora do runtime, typeof Temporal também dá "undefined", e o process.config desse binário traz v8_enable_temporal_support: 0, enquanto o zip oficial do 26.13.0 traz 1. O Node do Lambda foi compilado sem Temporal. Isso vale para a imagem de preview daquela data; o runtime pode mudar até o lançamento. Para quem pensa em trocar date-fns ou Luxon por Temporal junto com o upgrade, no Lambda essa troca ainda espera.

O roteiro, no seu projeto

É o que eu rodei, na ordem. Os comandos são para bash (no Windows, Git Bash).

  1. No Node 24 de sempre, veja o que ele já denuncia:

    NODE_OPTIONS="--trace-deprecation --pending-deprecation" npm test
    npm run build && node --trace-deprecation --pending-deprecation dist/main.js
    
  2. Procure o que ele não denuncia, e confira o jwa:

    node node26-scan.mjs .
    npm ls jwa
    
  3. Ponha um Node 26 ao lado do instalado, sem trocar o do sistema. Eu usei o zip oficial e conferi o SHA-256:

    curl -O https://nodejs.org/dist/v26.13.0/SHASUMS256.txt
    curl -O https://nodejs.org/dist/v26.13.0/node-v26.13.0-win-x64.zip
    grep " node-v26.13.0-win-x64.zip$" SHASUMS256.txt | sha256sum -c -
    unzip -q node-v26.13.0-win-x64.zip
    export PATH="$PWD/node-v26.13.0-win-x64:$PATH"
    node -v   # v26.13.0
    

    No Linux, o arquivo é o node-v26.13.0-linux-x64.tar.xz e o binário fica em bin/; não rodei essa variante.

  4. Com o 26 no PATH, na raiz do projeto:

    node load-deps.mjs
    npm test
    npm run build && node --trace-deprecation --pending-deprecation dist/main.js
    
  5. Procure no seu código read() sem argumento em stream de bytes, for await e toArray() que tratam cada pedaço como unidade, e cabeçalhos repassados para fetch. Nenhum script acha isso por você.

  6. Troque a versão em todos os lugares onde ela mora. No vertex-api são 5 node-version: 24 em 4 workflows, 4 FROM node:24-alpine no Dockerfile e 4 FROM public.ecr.aws/lambda/nodejs:24 no Dockerfile.lambda, além do @types/node. No pyxis-api são o .nvmrc (que 9 passos dos workflows leem), o engines, as imagens fixadas por digest nos dois Dockerfiles e no workflow que espelha as imagens, e o @types/node.

  7. Decida o destino do deploy antes de trocar a imagem: no Lambda, nodejs:26-preview serve para teste, não para produção.

O calendário que define a pressa

O Node 24 entrou em manutenção em 20 de outubro de 2026 e tem fim de vida em 30 de abril de 2028, segundo o schedule.json do projeto. O 26 virou LTS ("Lithium") em 28 de outubro de 2026 e vai até o fim de abril de 2029. Não há motivo de calendário para sair do 24 neste mês; o prazo que importa é abril de 2028.

O 26 também é a última versão do modelo antigo. A partir do 27, como o projeto anunciou em março, sai uma versão major por ano, em abril, que vira LTS em outubro. Toda versão vira LTS, e o papel das versões ímpares passa para um canal alpha, que começa em outubro de 2026. Para quem só usa LTS, segundo o próprio anúncio, pouco muda além da numeração.

Os dois Dockerfile.lambda continuam em nodejs:24 até o nodejs26.x sair do preview. O que ainda falta medir é o que este teste local não alcança: cold start e memória no runtime gerenciado, e como as sessões HTTP/2 do fetch se comportam num processo que o Lambda congela entre uma invocação e outra.

Comentários

Carregando comentários...