Node.js 25: cosa c’è davvero di nuovo, cosa si è rotto nell’ecosistema e se conviene aggiornare

Ci sono due tipi di upgrade Node. Il primo è “alzo la versione, tutto ok”. Il secondo è “alzo la versione e ora il backend mi spara errori da browser”. Node.js 25 ha fatto vivere a molti team il secondo scenario.

Con Docusaurus sembra surreale: DOMException [SecurityError]: Cannot initialize local storage without a --localstorage-file path durante docusaurus build.[1] Sintomi simili compaiono anche nel mondo CLI (Shopify) e nei test runner (Jest/Vitest).[2][3][4]

Qui il punto è: non è un “bug random nel tuo repo”. È una conseguenza del fatto che Node 25 ha abilitato Web Storage di default, ma localStorage su Node non è identico al browser (file-backed, quota, comportamento shared, niente cifratura).[7][5]

Eppure sarebbe un errore ridurre Node 25 alla saga di Web Storage. 25.4.0 e 25.5.0 portano miglioramenti maturi (require(esm) stabile, compile cache stabile, --build-sea) che riducono il dolore delle migrazioni e migliorano DX — se li adotti in modo controllato.[9][10][12]

Node 25 è una linea Current (odd). Si muove veloce: prima arrivano nuovi default, poi l’ecosistema trova edge case, poi escono release di stabilizzazione.[6]

Solo i concetti indispensabili per capire Node 25 senza perdersi nei flag.

25.0.0 è la base: V8 14.1, performance, web API e pulizia legacy. La vera “maturità” si vede in 25.4/25.5.[8][9][12]

Il problema non è che Web Storage sia “cattivo”. Il problema è che è cambiato il default, e parte del tooling ha iniziato a eseguire rami non testati su server.

nodejs/node #60704 descrive la regressione 25.2.0: “Cannot initialize local storage without a --localstorage-file path”, e collega toolchain rotti (webpack/jest/html-webpack-plugin).[5]

Vitest #8757 mostra un altro failure mode: in Node 25 localStorage non è più undefined e questo può rompere i mock.[4] Jest #15888 aggiunge un altro caso: test runner che fallisce con SecurityError su Node 25.2.0.[3]

Workaround rapido (se non ti serve): disabilitare temporaneamente Web Storage con il flag documentato nelle globals docs.[7]

Lezione per i team: anche se “non usi localStorage”, le dipendenze potrebbero farlo. Tenere Current in CI è un modo sano per intercettare sorprese.[6]

Una di quelle modifiche che non fa rumore, ma ti salva settimane in repo dove CJS ed ESM devono convivere.

La compile cache è un’ottimizzazione. È utile dove hai molti cold start o un grafo moduli grande (tool, CLI, worker).

Le docs node:module hanno una sezione concreta sulla portabilità: se cambiano gli absolute path, l’efficacia può scendere; portable aiuta a riusare la cache in più scenari.[10]

Esempio minimo:

import module from 'node:module';

module.enableCompileCache({ directory: '.node-compile-cache', portable: true });

In CI, gestisci esplicitamente la directory cache per non perderla tra i run.

Una delle modifiche più “product”: costruire un single executable non sembra più un rituale con injector esterno.

Non è una headline feature, ma riduce “micro wrapper” custom nei progetti con CI aziendale dietro proxy.

Snippet minimo:

import http from 'node:http';

const restore = http.setGlobalProxyFromEnv();
// restore();

In repo grandi, i watcher diventano un problema (node_modules, .git, output generati). Le docs descrivono ignore come opzione che accetta glob/RegExp/function/array.[15]

Esempio minimo:

import { watch } from 'node:fs';

watch('.', {
  recursive: true,
  ignore: ['**/node_modules/**', '**/.git/**'],
}, () => {});

I major release spesso fanno male per finalizzazione deprecations. SlowBuffer è l’esempio perfetto.[16]

Una checklist breve e realistica per i team.

Niente ideologia: Node 25 è ottimo come “detector” in CI, ed è utile per alcuni prodotti (CLI/agenti). Per i backend in produzione, LTS spesso vince per stabilità.