ESM‑ vs. CommonJS‑Abhängigkeitsfehler in Node‑Apps beheben

Wie ESM‑ vs. CommonJS‑Brüche aussehen

Node.js kennt zwei Wege, JavaScript‑Dateien zu laden. CommonJS ist der ältere Stil mit require() und module.exports. ESM (ECMAScript Modules) ist der neuere Stil mit import und export.

Die meisten Apps sind nicht „rein“ in einem Stil. Dein Code kann CommonJS sein, eine Abhängigkeit ESM‑only, und dein Dev‑Tool kann beim lokalen Ausführen Imports umschreiben. Genau diese Mischung verursacht Probleme.

Wenn Leute von einem „Modulformat‑Mismatch“ sprechen, meinen sie, dass eine Datei so geladen wird, als wäre sie CommonJS, obwohl sie ESM ist (oder umgekehrt). Beispiel: dein Code macht require('some-lib'), aber some-lib ist ESM‑only, also weigert sich Node, es per require() zu laden.

Deshalb passiert es oft direkt nachdem du eine Abhängigkeit hinzugefügt hast oder nach dem Deploy. Viele Dev‑Setups verstecken den Mismatch:

• TypeScript + ts‑node/tsx kann ESM‑artige Imports in der Entwicklung ausführen, selbst wenn die gebauten Dateien CommonJS sind.
• Bundler können lokal alles lauffähig machen, weil sie Abhängigkeiten bündeln; in Produktion läuft die Node‑Auflösung oft ungebündelt.
• Serverless‑ oder Docker‑Builds können eine andere Node‑Version oder eine andere Entry‑Datei verwenden als du lokal.

Ein typisches Szenario: ein Prototyp läuft mit npm run dev, bricht aber in Produktion, nachdem du ein kleines Utility‑Paket hinzugefügt hast. Lokal transpiliert der Dev‑Server alles on‑the‑fly. In Produktion startest du die kompilierten dist/index.js, Node behandelt sie als CommonJS, und das erste require() eines ESM‑only Pakets wirft.

Das betrifft viele Teams mit TypeScript, Next/Nuxt‑ähnlichen Toolchains und AI‑generierten Startern. Generierter Code mischt oft Signale (z. B. "type": "module" in package.json, aber CommonJS‑Output aus dem Build), was zu „funktioniert auf meinem Rechner“-Fehlern beim Laden von Modulen führt. Das Kernproblem ist einfach: Laufzeit und Build‑Output sprechen nicht dieselbe Modul‑Sprache.

Häufige Fehlermeldungen und was sie meist bedeuten

Wenn eine Node‑App ESM und CommonJS mischt, liefert die Absturzmeldung oft den schnellsten Hinweis. Die Formulierung sagt meist, was Node dachte, welche Datei es gerade geladen hat (ESM oder CJS) und was es zu laden versucht hat.

ERR_REQUIRE_ESM

Das passiert, wenn CommonJS‑Code require() auf ein Paket aufruft, das nur ESM liefert.

Du siehst es oft nach einem Upgrade einer Abhängigkeit, weil viele Bibliotheken in neuen Major‑Versionen zu ESM gewechselt sind. Häufige Auslöser: deine Datei wird als CommonJS behandelt (kein "type": "module", oder die Datei endet auf .cjs), du requiredst einen Deep‑Path, der die Paket‑Entrypoints umgeht, oder ein Tool (Test‑Runner, Config‑Loader) startet deinen Code in CommonJS, obwohl die App sonst ESM ist.

Die eigentliche Botschaft der Fehlermeldung: hör auf, require() dafür zu benutzen, oder wähle eine Paketversion, die noch CommonJS unterstützt.

„Cannot use import statement outside a module"

Das ist das Spiegelbild. Node behandelt die aktuelle Datei als CommonJS, aber sie enthält ESM‑Syntax wie import.

Häufige Ursachen: fehlendes "type": "module" in package.json, Verwendung von .js statt .mjs, oder ein Build‑Schritt, der ESM ausgibt, während du ihn in Produktion als CommonJS startest.

„Named export ... not found" (oder Überraschungen bei Default‑Exports)

Das kommt meist davon, dass man annimmt, ESM‑ und CommonJS‑Exportformen seien identisch. Ein CommonJS‑Modul exportiert oft ein einzelnes Objekt, während ESM benannte Exporte erwartet.

Ein schneller Geruchstest: wenn import { thing } from "pkg" fehlschlägt, aber import pkg from "pkg" funktioniert, hast du wahrscheinlich ein CommonJS‑Interop‑Problem.

„exports is not defined" und ähnliche Laufzeit‑Überraschungen

Das taucht oft auf, wenn Code, der CommonJS‑Globals (exports, require, module) erwartet, in einem ESM‑Kontext läuft, der diese nicht bereitstellt.

Ein typisches Muster ist „es funktionierte in der Entwicklung“. Ein Dev‑Server transpiliert alles, aber die Produktion läuft die gebauten Dateien direkt. Der Build‑Output enthält noch exports.foo = ..., und Node lädt sie als ESM — dann crasht es.

Schnelle Checks, bevor du etwas änderst

Bei Modulformat‑Fehlern ist die Versuchung groß, sofort "type": "module" zu kippen oder Imports umzuschreiben. Tu das nicht. Einige schnelle Prüfungen zeigen meist, ob du ein ESM‑only Paket eingefangen hast, ob du die falsche Entry‑Datei startest oder ob ein Tool deinen Code in einem unerwarteten Modus ausführt.

Beginne damit, die genaue Laufzeitumgebung zu bestätigen. Derselbe Code kann sich unter node, ts‑node, einem Test‑Runner oder einem Bundler unterschiedlich verhalten. Prüfe außerdem die Node‑Version in der Umgebung, die fehlschlägt (lokal, CI, Produktion). Defaults und Grenzfälle haben sich zwischen Node‑Releases geändert, und viele Hoster hinken lokaleren Versionen hinterher.

Bevor du Code anfasst, bestätige:

• Die Node‑Version und den Startbefehl in jeder Umgebung (z. B. node server.js vs. ein TypeScript‑Runner).
• Die erste Datei, die wirft, und ihre Extension: .cjs, .mjs, .js oder .ts.
• Das nächste package.json zu dieser Datei und ob es "type": "module" setzt.
• Den Abhängigkeitsnamen und den Dateipfad aus der ersten relevanten Stack‑Trace‑Zeile.
• Ob es nur in Dev oder nur in Produktion passiert und was sich unterscheidet (Build‑Output, Installationsmethode, Umgebungsvariablen).

Zwei Muster tauchen immer wieder auf. Zeigt der Stack‑Trace in node_modules/<pkg>/... und sagt, es könne nicht require()‑d werden, hast du wahrscheinlich ein ESM‑only Paket in CommonJS‑Code geladen. Zeigt er auf deinen gebauten Output (z. B. dist/index.js), dann widersprechen sich Build und Laufzeit beim Modulformat.

Ein kleines Beispiel: ein Prototyp läuft lokal mit ts‑node (das ESM eventuell anders handhabt), aber Produktion läuft einfach node dist/server.js. Dieser Wechsel allein kann den Mismatch aufzeigen, den du beheben musst.

Schritt‑für‑Schritt: Diagnose des Modulformat‑Mismatch

Der schnellste Weg ist, das Raten zu stoppen und herauszufinden, wo Node die Grenze zwischen ESM und CommonJS zieht.

1) Fang beim ersten Frame aus deinem Code an

Öffne den Fehler und scrolle zum Stack‑Trace. Ignoriere zunächst die langen Listen in node_modules. Finde den ersten Frame, der auf eine Datei in deinem Repo zeigt, und notiere Dateiname und Extension, die Zeile, die den Ladevorgang ausgelöst hat (ein import, require oder dynamisches import()), und das nächste package.json, das diese Datei kontrolliert.

Dieser Frame ist meist der Ort, an dem die falsche Modulentscheidung sichtbar wird.

2) Bestätige, wie Node diese Datei interpretiert (ESM oder CJS)

Node entscheidet ESM vs CJS hauptsächlich über Dateiendungen und package.json:

• .mjs läuft als ESM.
• .cjs läuft als CommonJS.
• .js hängt vom type in package.json ab (wenn "type": "module", ist es ESM; sonst CommonJS).

Eine übliche Fallstrick: du denkst, du bist in CommonJS, weil du require() geschrieben hast, aber dein Paket ist type: module, also ist die .js‑Datei tatsächlich ESM.

3) Untersuche die Entry‑Points der Abhängigkeit

Schau dir die Abhängigkeit an, die beim Fehler geladen wird. In ihrem node_modules/<pkg>/package.json prüfe, was Node auswählt:

• main (oft CommonJS)
• module (oft ESM, aber Node nutzt das nicht immer direkt)
• exports (kann unterschiedliche Dateien für import vs require zuordnen)

Wenn exports existiert, entscheidet es oft alles. Ein Paket kann ESM für import exportieren, aber keinen CommonJS‑Pfad für require anbieten — das führt zu ERR_REQUIRE_ESM.

4) Reproduziere mit minimalem Snippet

Erstelle eine kleine Datei neben deiner App (oder in einem Scratch‑Ordner) und teste nur den problematischen Import.

// test-load.js
const pkg = require("the-problem-package");
console.log(pkg);

Und die ESM‑Variante:

// test-load.mjs
import pkg from "the-problem-package";
console.log(pkg);

Wenn das eine funktioniert und das andere nicht, hast du bestätigt, dass es ein Formatmismatch ist (nicht deine Geschäftslogik).

5) Entscheide: App, Build oder Abhängigkeit ändern

Nutze das Ergebnis, um den risikoärmsten Fix zu wählen:

• Ändere den Modulmodus deiner App (Extensions oder type), wenn du den Großteil des Codes kontrollierst.
• Passe dein Build/Transpile‑Output an, wenn du TypeScript kompilierst oder bundlelt.
• Ändere die Abhängigkeit (pinne eine Version, wechsle das Paket oder nutze einen anderen Entry), wenn das Paket dein Format nicht mehr unterstützt.

Gezielt fixes in package.json (type, main, exports)

Viele Modulformat‑Crashes lassen sich beheben, ohne die ganze Codebasis umzuschreiben. Ziel ist, klarzumachen, ob dein Paket (oder eine Abhängigkeit) ESM, CommonJS oder beides ist.

Beginne mit "type". "type": "module" setzt das Default für jede .js‑Datei in diesem Paket zu ESM. Das ist sinnvoll, wenn du komplett zu ESM wechselst, kann aber eine Kaskade von require()‑Fehlern auslösen. Wenn du noch CommonJS‑Dateien hast, erwäge, "type" nicht global zu setzen und stattdessen pro Datei zu entscheiden.

Wenn du unterschiedliche Verhaltensweisen pro Datei brauchst, nutze besser Extensions statt globale Schalter:

• .cjs für Dateien, die CommonJS sein müssen (require, module.exports).
• .mjs für Dateien, die ESM sein müssen (import, export).
• .js nur, wenn das Paket‑Default (type) dem entspricht, was du willst.

Prüfe als Nächstes deine Entry‑Points. "main" ist der klassische Node‑Entry und meist CommonJS. Manche Bundler sehen "module" als ESM‑Entry. Wenn du beide Builds brauchst, verweise auf unterschiedliche Dateien (z. B. dist/index.cjs vs dist/index.js).

"exports" ist mächtig und überrascht oft. Sobald es da ist, kann es tiefe Importe wie some-lib/dist/internal.js blockieren, selbst wenn diese Datei existiert. Ältere Tools und Test‑Runner können daraufhin ebenfalls fehlschlagen. Nutze "exports", um nur das freizugeben, was du willst, aber sei explizit für ESM‑ und CommonJS‑Bedingungen.

Wenn du Entry‑Points änderst, vermeide Breaks für Konsumenten: behalte "main" stabil, während du "exports" einführst, exportiere sowohl import‑ als auch require‑Targets, wenn du beides unterstützen willst, und ersetze tiefe Pfade durch dokumentierte öffentliche Exports.

Fixes über Build‑ und Transpile‑Einstellungen

Viele ESM/CJS‑Fehler entstehen nicht wirklich durch die Abhängigkeit, sondern durch Build‑Output, der nicht zum Runtime‑Verhalten passt.

TypeScript‑Einstellungen, die entscheiden, was Node lädt

TypeScript kann Code ausgeben, der im Editor okay aussieht, aber die erzeugten Dateien passen nicht zur Laufzeit. Wenn du kompiliertes JavaScript ausführst, prüfe diese Optionen:

• compilerOptions.module: CommonJS erzeugt require(...); NodeNext oder ESNext erzeugen import.
• compilerOptions.moduleResolution: NodeNext versteht ESM‑Regeln (Dateiendungen, exports).
• compilerOptions.esModuleInterop und allowSyntheticDefaultImports: diese können Imports kompilierbar machen, auch wenn die Laufzeit‑Interop noch falsch ist.
• outDir: stelle sicher, dass der gesamte Laufzeitcode aus einem Ordner kommt (gewöhnlich dist).

Eine einfache Regel: kompiliere ins gleiche Modulformat, das dein Node‑Prozess erwartet. Wenn deine App ESM ist, gib ESM aus. Wenn CommonJS, gib CommonJS aus.

Wenn der Bundler in Dev „repariert“, aber Node später bricht

Bundler und Dev‑Server rewriten oder bündeln oft Abhängigkeiten, sodass die App während der Entwicklung funktioniert. In Produktion läuft plain Node gegen deine gebauten Dateien, und plötzlich treten ESM/CJS‑Fehler auf.

Um Überraschungen zu reduzieren, starte lokal den Produktions‑Startbefehl gegen den kompilierten Output, nicht gegen den Dev‑Server.

Vermeide das „src vs dist“ Durcheinander

Fehler kommen oft wieder, wenn die Laufzeit einige Dateien aus src und andere aus dist importiert. Das mischt Modul‑Systeme und Dateiendungen.

Halte es sauber:

• Sorge dafür, dass Produktion nur dist (oder nur src, wenn du wirklich TS direkt laufen lässt) nutzt.
• Entferne alte Build‑Artefakte vor dem Build (stale Dateien können noch importiert werden).
• Nutze konsistente Importpfade, die auf gebaute Dateien zeigen.

Fixes durch Anpassung, Pinnen oder Wechseln von Abhängigkeiten

Manchmal ist der schnellste Fix in der Wahl der Abhängigkeit, nicht in deinem App‑Code. Behandle die Abhängigkeit als Variable: wähle eine kompatible Version, nutze einen unterstützten Entry‑Point oder tausche auf eine Alternative.

Wechsel auf eine CJS‑freundliche Alternative (wenn möglich)

Wenn deine App CommonJS ist (benutzt require) und eine Abhängigkeit zu ESM‑only gewechselt ist, ist ein Wechsel oft sauberer als nur für ein Paket einen Build‑Hack einzuführen. Das gilt besonders für kleine Utilities.

Beim Auswählen einer Alternative: achte darauf, dass sie das von dir genutzte Modulsystem unterstützt, zu deiner Node‑Version passt und keine tiefen Importe erfordert.

Pinne eine kompatible Version (mit Vorsicht)

Pinnen kann die schnellste Methode sein, um akute Probleme zu stoppen, besonders wenn ein Release das Modulformat umgedreht hat. Sieh das als temporären Safeguard: deploy, plane den echten Fix (App zu ESM migrieren oder Abhängigkeit ersetzen) und behalte Sicherheitsfixes im Auge, die du mit älteren Versionen verpassen könntest.

Nutze den dokumentierten Entry‑Point, nicht einen Deep‑Import

Viele Brüche entstehen, weil Code interne Pfade importiert hat, die früher funktioniert haben, z. B. some-lib/dist/index.js. Nach einem Update fügt das Paket ein exports‑Mapping hinzu und blockiert tiefe Pfade. Die Lösung ist meist, vom öffentlichen Entry zu importieren (oder einen dokumentierten Subpath‑Export zu nutzen).

Wenn die Abhängigkeit ESM‑only ist, deine App aber CJS ist

Du hast drei realistische Optionen: deine App auf ESM umstellen, die Abhängigkeit ersetzen oder sie isolieren.

Isolation ist oft ein guter Kompromiss: lade das ESM‑Paket in einem kleinen Wrapper‑Modul (mittels dynamischem import()), und halte den Rest deines Codes CommonJS, während du eine umfassendere Migration planst.

Häufige Fallen, durch die das Problem wiederkehrt

Viele ESM/CommonJS‑Fixes schlagen beim zweiten Mal fehl, weil die App inkonsistent bleibt. Es funktioniert in einem Befehl (oft dev), bricht aber in Tests, CI oder Produktion, weil dort ein anderer Entry‑Point oder Toolchain genutzt wird.

Mischung von require() und import auf denselben Laufzeitpfad

Die Falle ist nicht, beide Stile irgendwo im Repo zu haben. Die Falle ist, wenn derselbe Codepfad sowohl unter ESM‑ als auch unter CJS‑Regeln ausgeführt werden kann.

Beispiel: du nutzt dynamisches import() für eine ESM‑only Abhängigkeit in einer Route, aber ein CLI‑Skript oder ein Test trifft weiterhin den alten require()‑Pfad.

Wenn du Formate mischen musst, halte die Grenze klar: ein Wrapper‑Modul, das den dynamischen Import erledigt, und alles andere ruft diesen Wrapper an.

TypeScript‑Source statt kompiliertem JS ausliefern

Das tritt auf, wenn du einen Ordner deployst, der noch .ts enthält (oder ESM‑geprägte Outputs), während die Laufzeit CommonJS erwartet (oder umgekehrt). Lokal sieht das oft okay aus, weil ts‑node, ein Dev‑Server oder ein Bundler kompiliert.

Ein einfacher Check: schau dir an, was tatsächlich deployed wird. Wenn dein Server mit node dist/index.js startet, stelle sicher, dass dist existiert und das erwartete Format enthält. Prüfe auch, dass deine Package‑Entry‑Points (main, exports) auf gebaute Dateien und nicht auf Source zeigen.

Dev‑Tooling, das Modul‑Laden patcht

Test‑Runner, Dev‑Server und Transpiler können Probleme durch On‑the‑fly‑Transformationen kaschieren. Produktion läuft plain Node.js und trifft dann auf den rohen Mismatch.

Wenn Dev einen Custom‑Runner nutzt, Produktion aber node direkt, betrachte „funktioniert in Dev“ als unbelegt, bis du den Produktions‑Startbefehl lokal ausführst.

Ein "type": "module" hinzufügen, um eine Datei zu reparieren — und alles andere zu zerstören

"type": "module" ändert die Bedeutung jeder .js‑Datei im Paket. Es kann sofort require()‑Aufrufe, Config‑Dateien, die Tools als CommonJS erwarten, und alte Abhängigkeiten, die CommonJS‑Entrypoints voraussetzen, brechen.

Wenn du nur in einem Bereich ESM brauchst, überlege .mjs für ESM‑Dateien und .cjs für CommonJS‑Dateien, oder isoliere die Änderung in einem Subpaket anstatt das ganze Projekt umzuschalten.

Dual‑Package‑Gefahren (unterschiedliches Verhalten in ESM vs CJS)

Einige Bibliotheken liefern sowohl ESM‑ als auch CJS‑Builds. Node wählt je nach import oder require und nach exports‑Bedingungen einen anderen Entry. Das Schwierige: beide Versionen können „funktionieren“, sich aber leicht unterschiedlich verhalten (Default‑Export‑Form, Seiteneffekte).

Wenn das Problem immer wiederkommt, pinne die Dependency‑Version und nutze den dokumentierten Importstil. Wenn die Bibliothek unzuverlässig bleibt, ist ein Wechsel zu einer einfacheren Abhängigkeit oft die schnellere langfristige Lösung.

Beispiel: Ein Prototyp, der in Dev läuft, in Produktion aber bricht

Eine typische Story: lokal sieht alles gut aus, dann explodieren die Logs nach dem Deploy. Lokal hast du node server.js gestartet, die API hat geantwortet. In Produktion startet der Prozess, trifft auf die erste Anfrage und crasht.

Setup: der Prototyp hat eine CommonJS‑Serverdatei (server.js) mit überall require(). Eine hinzugefügte Abhängigkeit ist ESM‑only.

Der Crash sieht oft so aus:

Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.
Instead change the require of ... to a dynamic import()

Das Grundproblem ist klar: eine CommonJS‑Datei versucht, ein ESM‑only Paket mit require() zu laden. Node lehnt das ab, weil ESM und CommonJS unterschiedliche Lade‑Regeln haben.

Zwei Fixe funktionieren häufig, abhängig davon, wie viel du ändern willst.

Fix‑Option 1: eine Datei (oder die Grenze) auf ESM umstellen

Wenn die Serverdatei der einzige Ort ist, der das ESM‑only Paket lädt, verschiebe diese Grenze zu ESM.

Du kannst server.js zu server.mjs umbenennen und require() durch import ersetzen, oder server.js belassen und das ESM‑Paket per dynamischem Import laden:

const esmLib = await import('esm-only-lib');

Damit bleibt der Großteil deines Codes unverändert, während das ESM‑Paket korrekt geladen wird.

Fix‑Option 2: die Abhängigkeit gegen eine CommonJS‑freundliche Alternative tauschen

Wenn das Umstellen einer zentralen Datei auf ESM weitere Änderungen (Tests, Configs, andere Imports) nach sich zieht, ist ein Austausch oft schneller. Wähle eine Abhängigkeit, die CommonJS (oder beide Builds) unterstützt, und aktualisiere die Nutzung.

Um die Korrektur zu verifizieren, starte nicht einfach den Server im selben Dev‑Umfeld neu. Mache einen sauberen Rebuild und Cold Start: entferne Build‑Output und Caches, installiere Dependencies neu, starte frisch und rufe den Endpunkt auf, der zuvor crashte.

Nächste Schritte für einen sauberen, produktionsreifen Fix

Triff schnell eine Entscheidung und wende sie konsistent an: ändere das App‑Format, wenn der Großteil deines Codes und Toolings in eine Richtung tendiert; ändere die Abhängigkeit, wenn nur ein Paket aus der Reihe tanzt; oder passe den Build an, wenn der Source in Ordnung, aber der Output falsch ist.

Wenn du andere um Hilfe bittest, bring einen sauberen Snapshot mit:

• Die exakte Fehlermeldung und den vollständigen Stack‑Trace
• Deine package.json (besonders type, main, exports, und dependencies)
• Deine Node‑Version (lokal, CI, Produktion)
• Die Datei und Zeile, die den Fehler auslöst
• Den genauen Run‑Befehl (inkl. Build‑Schritt)

Wenn das von einem AI‑generierten Prototypen stammte, der oft mehrfach gepatcht wurde, treten Modulmismatches häufig zusammen mit anderen Produktionsproblemen auf (kaputte Auth, exponierte Secrets, schwer wartbare Struktur). FixMyMess (fixmymess.ai) konzentriert sich darauf, solche geerbten Codebasen stabil zu bekommen: wir diagnostizieren, wenden die kleinstmöglichen sicheren Änderungen an und verifizieren mit manuellen Checks. Wenn du einen risikoarmen Einstieg willst, kann ihr kostenloses Code‑Audit schnell zeigen, welche Modulgrenze falsch ist und welcher Fix‑Pfad am sichersten ist.