Dobbelt ESM- og CJS-package-output

ESM (ECMAScript Modules) er den officielle JavaScript-modulstandard, der bruger syntaksen import og export. ESM kan analyseres statisk — bundlere kan på byggetidspunktet præcist afgøre, hvilke eksporter der bruges, så tree-shaking bliver mulig. Moderne browsere og Node.js understøtter begge ESM indbygget.

CJS (CommonJS) bruger syntaksen require() og module.exports. Det var Node.js' oprindelige modulsystem og er stadig nødvendigt af hensyn til kompatibilitet med ældre Node.js-miljøer, Jest (som historisk brugte CJS) og kode, der bruger require(). CJS evalueres dynamisk, hvilket gør tree-shaking vanskeligere.

En moderne npm-pakke bør levere både ESM og CJS for at maksimere kompatibiliteten. ESM-brugere (Vite, Next.js og moderne bundlere) får importer, der kan tree-shakes. CJS-brugere (ældre Node.js-scripts og Jest uden konfiguration) får kompatibilitet med require(). Feltet exports i package.json fortæller Node og bundlere, hvilket format der skal bruges.

Feltet exports i package.json er den moderne måde at definere betingede indgangspunkter på. Eksempel: { '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }. Bundlere og Node.js 12+ læser exports for automatisk at vælge det korrekte format.

Ældre værktøjer forstår ikke feltet exports. Af hensyn til kompatibiliteten skal du også angive: main, der peger på CJS-resultatet (ældre Node require-tilbagefald), og module, der peger på ESM-resultatet (et tip til webpack/rollup, ikke standardiseret, men bredt understøttet). Moderne værktøjer foretrækker exports, mens ældre værktøjer falder tilbage til main/module.

Hvis du angiver "type": "module" i package.json, behandles alle .js-filer i pakken som ESM. Hvis du udgiver i begge formater, skal du derfor bruge eksplicitte filendelser: Brug .mjs til ESM-filer og .cjs til CJS-filer, når type er module, eller omvendt. tsup håndterer dette automatisk.

Ved eksplicit at bruge filendelserne .mjs (ESM) og .cjs (CJS) markeres formatet uanset type-feltet. Det fjerner tvetydighed. tsup kan producere: index.js (ESM) og index.cjs (CJS), når format er ['esm', 'cjs'], og intet type-felt er angivet, hvilket følger den mest udbredte konvention.

Når en pakke leverer både ESM- og CJS-formater, kan brugerens bundler indlæse begge versioner i samme proces — f.eks. ESM-versionen til hovedappen og CJS-versionen til en Jest-test. Hvis pakken har tilstand på modulniveau (f.eks. en React-kontekst), har begge instanser uafhængig tilstand. Dette er risikoen ved dobbeltpakker.

For at mindske risikoen skal du holde tilstand på modulniveau ude af biblioteket (ingen singleton-mønstre), bruge betingelserne i exports præcist for at sikre, at kun ét format indlæses, og dokumentere, at tests skal konfigurere deres bundler til at bruge ESM. Risikoen er primært relevant for biblioteker med delte singletoner.

Kontrollér, at begge formater fungerer efter bygningen. Test CJS: node -e "const lib = require('./dist/cjs/index.js'); console.log(lib)". Test ESM: node --input-type=module --eval "import { Component } from './dist/esm/index.js'; console.log(Component)". Begge bør kunne indlæses uden fejl, før pakken publiceres.

Feltet exports understøtter flere indgangspunkter: { '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }. Brugerne kan derefter importere fra 'your-lib' eller 'your-lib/utils' og får det korrekte format.

ESM bruger import/export og muliggør tree-shaking. CJS bruger require() af hensyn til Node.js-kompatibilitet. Udgiv begge via feltet exports i package.json med betingelserne import/require. Ældre tilbagefald: main (CJS) og module (ESM). Brug .mjs/.cjs-udvidelser eller type: module til eksplicit markering af formatet. Test begge formater med node CLI efter bygningen. Vær opmærksom på risikoen ved dobbeltpakker, når der bruges singleton-tilstand.