ESM- und CJS-Ausgaben für Dual Packages

ESM (ECMAScript Modules) ist der offizielle JavaScript-Modulstandard, der die Syntax import und export verwendet. ESM lässt sich statisch analysieren — Bundler können bereits zur Build-Zeit exakt bestimmen, welche Exporte verwendet werden, und dadurch Tree-Shaking ermöglichen. Moderne Browser und Node.js unterstützen ESM nativ.

CJS (CommonJS) verwendet die Syntax require() und module.exports. Es war das ursprüngliche Modulsystem von Node.js und wird weiterhin für die Kompatibilität mit älteren Node.js-Umgebungen, mit Jest (das historisch CJS verwendet hat) und mit Code benötigt, der require() verwendet. CJS wird dynamisch ausgewertet, was Tree-Shaking erschwert.

Ein modernes npm-Paket sollte sowohl ESM als auch CJS ausliefern, um die Kompatibilität zu maximieren. ESM-Nutzer (Vite, Next.js, moderne Bundler) erhalten Imports, die sich per Tree-Shaking reduzieren lassen. CJS-Nutzer (ältere Node.js-Skripte, Jest ohne Konfiguration) erhalten Kompatibilität mit require(). Das exports-Feld von package.json teilt Node und Bundlern mit, welches Format verwendet werden soll.

Das Feld exports in package.json ist die moderne Möglichkeit, bedingte Einstiegspunkte zu definieren. Beispiel: { '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }. Bundler und Node.js 12+ lesen exports, um automatisch das richtige Format auszuwählen.

Ältere Tools verstehen das exports-Feld nicht. Legen Sie zur Kompatibilität außerdem Folgendes fest: main zeigt auf die CJS-Ausgabe (require-Fallback für ältere Node-Versionen) und module auf die ESM-Ausgabe (ein Hinweis für webpack/rollup, nicht standardisiert, aber weit verbreitet unterstützt). Moderne Tools bevorzugen exports, ältere Tools greifen auf main/module zurück.

Wenn Sie "type": "module" in package.json festlegen, werden alle .js-Dateien im Paket als ESM behandelt. Wenn Sie beide Formate ausliefern, benötigen Sie daher explizite Erweiterungen: Verwenden Sie .mjs für ESM-Dateien und .cjs für CJS-Dateien, wenn type auf module gesetzt ist, oder umgekehrt. tsup übernimmt dies automatisch.

Die explizite Verwendung der Dateierweiterungen .mjs (ESM) und .cjs (CJS) kennzeichnet das Format unabhängig vom type-Feld. Dadurch werden Mehrdeutigkeiten vermieden. tsup kann bei format: ['esm', 'cjs'] und ohne gesetztes type-Feld Folgendes ausgeben: index.js (ESM) und index.cjs (CJS), entsprechend der gängigsten Konvention.

Wenn ein Paket sowohl ESM- als auch CJS-Formate bereitstellt, kann der Bundler eines Nutzers beide Versionen im selben Prozess laden — beispielsweise die ESM-Version für die Hauptanwendung und die CJS-Version für einen Jest-Test. Verfügt das Paket über einen Zustand auf Modulebene (etwa einen React-Kontext), haben beide Instanzen einen unabhängigen Zustand. Das ist die Dual-Package-Falle.

Um die Gefahr zu mindern, halten Sie Zustände auf Modulebene aus Ihrer Bibliothek heraus (keine Singleton-Muster), verwenden Sie die exports-Bedingungen präzise, damit nur ein Format geladen wird, und dokumentieren Sie, dass Tests ihren Bundler für die Verwendung von ESM konfigurieren sollten. Die Gefahr betrifft hauptsächlich Bibliotheken mit gemeinsam genutzten Singletons.

Überprüfen Sie nach dem Build, ob beide Formate funktionieren. CJS testen: node -e "const lib = require('./dist/cjs/index.js'); console.log(lib)". ESM testen: node --input-type=module --eval "import { Component } from './dist/esm/index.js'; console.log(Component)". Beide sollten vor der Veröffentlichung ohne Fehler aufgelöst werden.

Das exports-Feld unterstützt mehrere Einstiegspunkte: { '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }. Nutzer importieren dann aus 'your-lib' oder 'your-lib/utils' und erhalten das richtige Format.

Was ist der Hauptzweck des Felds exports in der package.json einer Bibliothek?

ESM verwendet import/export und ermöglicht Tree-Shaking. CJS verwendet require() für die Kompatibilität mit Node.js. Liefern Sie beide Formate über das exports-Feld von package.json mit import-/require-Bedingungen aus. Legacy-Fallbacks: main (CJS) und module (ESM). Verwenden Sie .mjs/.cjs-Erweiterungen oder type: module, um das Format eindeutig zu kennzeichnen. Testen Sie beide Formate nach dem Build über die node-CLI. Achten Sie bei Singleton-Zuständen auf die Dual-Package-Falle.