ES-Module versus CommonJS in Node.js

Worum es geht

CommonJS (CJS) ist Nodes ursprüngliches Modulsystem: require() lädt synchron zur Laufzeit, und ein Modul exportiert das, was es module.exports zuweist. ES-Module (ESM) sind der Sprachstandard: import und export sind statisch und werden aufgelöst, bevor der Modulkörper ausgeführt wird, das Laden erfolgt asynchron, Top-Level-await ist erlaubt, und import.meta trägt Modul-Metadaten. Node entscheidet pro Datei: .mjs ist immer ESM, .cjs immer CJS, und .js folgt dem "type"-Feld der nächstgelegenen package.json. Fehlt ein "type"-Feld, bezeichnet die Packages-Dokumentation die Datei als mehrdeutig: aktuelle Node-Versionen führen sie zunächst als CommonJS aus und werten sie, falls der Parser ES-Modul-Syntax findet, als ES-Modul neu aus (Syntax-Erkennung); ältere Versionen behandeln sie schlicht als CommonJS. Die ESM-Dokumentation listet auf, was in ESM fehlt (require, module.exports, __filename, __dirname), und die Ersatzlösungen: import.meta.filename, import.meta.dirname, import.meta.resolve() und module.createRequire(). ESM kann CommonJS importieren (der Default-Import ist module.exports), und aktuelle Node-Versionen können ein ES-Modul mit require() laden, solange sein Abhängigkeitsgraph kein Top-Level-await enthält.

Warum es wichtig ist

Das Vermischen der beiden Systeme steckt hinter den häufigsten Startfehlern in Node-Projekten: "Cannot use import statement outside a module", ERR_REQUIRE_ESM, exports is not defined. Testrunner, TypeScript-Ausgabe und Bundler haben jeweils eine eigene Moduleinstellung, und eine Fehlpassung schlägt zur Laufzeit fehl statt beim Build.

So wird es angewendet

• Bei neuem Code "type": "module" in der package.json setzen und durchgängig ESM schreiben; die wenigen Dateien, die CommonJS bleiben müssen, auf .cjs benennen.
• Relative Imports in ESM müssen die Dateiendung enthalten (./util.js, ./dir/index.js); der Resolver rät nicht.
• JSON wird mit einem Attribut importiert: import cfg from "./cfg.json" with { type: "json" }.
• Bibliotheken, die beide Formate ausliefern: "exports" mit import- und require-Bedingungen deklarieren und vorher die Packages-Dokumentation samt ihrem verlinkten Beispiel-Repository zu Dual Packages lesen; ein Paket, das über beide Einstiegspunkte geladen wird, existiert doppelt, mit getrenntem Modulzustand (die Dual-Package-Gefahr).
• Im Browser müssen Modul-Skripte mit einem JavaScript-MIME-Typ wie text/javascript ausgeliefert werden; MDN dokumentiert den Fehler bei strikter MIME-Typ-Prüfung für .mjs-Dateien, die anders ausgeliefert werden.

Stolpersteine

Zirkuläre Imports verhalten sich unterschiedlich: ESM-Bindungen sind live, können aber bei frühem Lesen noch uninitialisiert sein. require() eines ESM, das Top-Level-await verwendet, wirft ERR_REQUIRE_ASYNC_MODULE; stattdessen import() verwenden. Ein Compiler, der require-Aufrufe in ein "type": "module"-Paket schreibt, erzeugt Code, der beim Laden scheitert; die Modul-Ausgabeeinstellung des Compilers mit der Laufzeitumgebung abstimmen.