Node.js 25: was wirklich neu ist, was im Ökosystem kaputtging und ob sich ein Upgrade lohnt

Es gibt zwei Arten von Node-Upgrades. Die erste: „Version hoch, alles läuft“. Die zweite: „Version hoch, und plötzlich kommen browserartige Fehler im Backend“. Node.js 25 hat viele Teams in die zweite Kategorie geschubst.

Bei Docusaurus wirkt das absurd: DOMException [SecurityError]: Cannot initialize local storage without a --localstorage-file path beim docusaurus build.[1] Ähnliche Symptome tauchen auch bei CLIs (Shopify) und Test-Runnern (Jest/Vitest) auf.[2][3][4]

Wichtig: Das ist nicht einfach „ein zufälliger Bug in eurem Repo“. Es ist eine Folge davon, dass Node 25 Web Storage per Default aktiviert — und Node-localStorage ist eben kein 1:1 Browser-Storage (file-backed, Quota, shared, unencrypted).[7][5]

Und trotzdem: Node 25 ist mehr als die Web-Storage-Saga. 25.4.0 und 25.5.0 bringen reife Verbesserungen (require(esm) stable, Compile Cache stable, --build-sea), die Migrationen spürbar vereinfachen — wenn man sie bewusst einführt.[9][10][12]

Node 25 ist eine Current-Line (odd). Sie entwickelt sich schnell: neue Defaults, dann Edge-Cases, dann Stabilisierung.[6]

Genug Vokabular, damit Node 25 als Text Sinn ergibt.

25.0.0 ist das Fundament: V8 14.1, Performance, Web APIs und Legacy-Cleanup. Die „Reife“ der Line zeigt sich in 25.4/25.5.[8][9][12]

Das Problem ist nicht, dass Web Storage „schlecht“ wäre. Das Problem ist, dass der Default geändert wurde, und Tooling auf einmal Codepfade ausführt, die nie serverseitig getestet wurden.

nodejs/node #60704 beschreibt die 25.2.0 Regression: “Cannot initialize local storage without a --localstorage-file path” und verweist auf kaputte Toolchains (webpack/jest/html-webpack-plugin).[5]

Vitest #8757 zeigt einen anderen Failure Mode: In Node 25 ist localStorage nicht mehr undefined, was Mocks in Test-Umgebungen brechen kann.[4] Jest #15888 ist ein weiterer Beleg: der Runner scheitert mit SecurityError auf Node 25.2.0.[3]

Schneller Incident-Workaround (wenn Storage nicht gebraucht wird): Web Storage temporär per Flag deaktivieren (steht in den globals docs).[7]

Team-Lektion: Auch wenn ihr „kein localStorage nutzt“, eure Dependencies könnten. Deshalb ist Current in CI als Frühwarnsystem sinnvoll.[6]

Eine dieser Änderungen, die nicht laut ist, aber in großen Repos wochenlang Arbeit spart.

Compile Cache ist eine Optimierung. Sie hilft besonders bei vielen Cold Starts oder großen Modulgraphen (Tools, CLI, Worker).

Die node:module Docs erklären Portabilität sehr konkret: Wenn absolute Pfade sich ändern, verliert der Cache an Effektivität; portable hilft beim Reuse.[10]

Minimaler Versuch:

import module from 'node:module';

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

In CI lohnt es sich, das Cache-Verzeichnis explizit zu managen, damit es nicht “verdampft”.

Eine der produktivsten Änderungen in der Line: Single Executable bauen sieht nicht mehr wie ein externes Injector-Ritual aus.

Keine „Headline“, aber ein DX-Gewinn: weniger kleine Proxy-Wrapper in Projekten mit Enterprise-CI.

Minimal:

import http from 'node:http';

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

In großen Repos sind Watcher ein eigener Schmerz (node_modules, .git, Generated Output). Die Docs beschreiben ignore als Option (glob/RegExp/function/array).[15]

Minimalbeispiel:

import { watch } from 'node:fs';

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

Major-Releases tun oft weh durch Deprication-Finalisierung. SlowBuffer ist das Paradebeispiel.[16]

Kurze, praxisnahe Checkliste.

Ohne Religion: Node 25 ist super als CI-Frühwarnsystem und für bestimmte Produkte (CLI/Agents). Für Production Backends gewinnt meist LTS durch Stabilität.

Quellen in Erscheinungsreihenfolge (Position = [n]).

Für die meisten Teams: Prod auf LTS, Node 25 in CI als Frühwarnsystem, und 25.4/25.5 Features (require(esm), Compile Cache, build-sea) zuerst in isolierten Experimenten (CLI/Worker). DX hoch, Risiko runter.