ESM- og CJS-utdata i samme pakke

ESM (ECMAScript Modules) er den offisielle JavaScript-modulstandarden som bruker syntaksen import og export. ESM kan analyseres statisk – bundlere kan fastslå nøyaktig hvilke eksporter som brukes under byggingen, noe som muliggjør tree-shaking. Moderne nettlesere og Node.js støtter ESM innebygd.

CJS (CommonJS) bruker syntaksen require() og module.exports. Det var Node.js sitt opprinnelige modulsystem og trengs fortsatt for kompatibilitet med eldre Node.js-miljøer, Jest (som historisk brukte CJS) og kode som bruker require(). CJS evalueres dynamisk, noe som gjør tree-shaking vanskeligere.

En moderne npm-pakke bør leveres i både ESM- og CJS-format for å maksimere kompatibiliteten. Brukere av ESM (Vite, Next.js og moderne bundlere) får importer som kan tree-shakes. Brukere av CJS (eldre Node.js-skript og Jest uten konfigurasjon) får kompatibilitet med require(). Feltet exports i package.json forteller Node og bundlere hvilket format som skal brukes.

Feltet exports i package.json er den moderne måten å definere betingede inngangspunkter på. Eksempel: { '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }. Bundlere og Node.js 12+ leser exports for å velge riktig format automatisk.

Eldre verktøy forstår ikke feltet exports. For kompatibilitet bør du også angi: main, som peker på CJS-utdataene (reserveordning for eldre Node require), og module, som peker på ESM-utdataene (et hint til webpack/rollup, ikke-standardisert, men bredt støttet). Moderne verktøy foretrekker exports, mens eldre verktøy faller tilbake til main/module.

Hvis du setter "type": "module" i package.json, behandles alle .js-filer i pakken som ESM. Hvis du leverer begge formater, trenger du derfor eksplisitte filendelser: bruk .mjs for ESM-filer og .cjs for CJS-filer når type er module, eller omvendt. tsup håndterer dette automatisk.

Bruk av filendelsene .mjs (ESM) og .cjs (CJS) markerer formatet eksplisitt, uavhengig av type-feltet. Dette unngår tvetydighet. tsup kan produsere: index.js (ESM) og index.cjs (CJS) når format er ['esm', 'cjs'] og ingen type-felt er angitt, i tråd med den vanligste konvensjonen.

Når en pakke tilbyr både ESM- og CJS-formater, kan brukerens bundler laste inn begge versjonene i samme prosess – for eksempel ESM-versjonen for hovedappen og CJS-versjonen for en Jest-test. Hvis pakken har tilstand på modulnivå (for eksempel en React-kontekst), har begge instansene uavhengig tilstand. Dette er faren ved dual package.

Du kan redusere faren på følgende måter: Hold tilstand på modulnivå utenfor biblioteket (unngå singleton-mønstre), bruk exports-betingelsene presist for å sikre at bare ett format lastes inn, og dokumenter at tester bør konfigureres til å bruke ESM. Faren er hovedsakelig relevant for biblioteker med delte singletons.

Kontroller at begge formatene fungerer etter byggingen. 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 løses uten feil før publisering.

Feltet exports støtter flere inngangspunkter: { '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }. Brukerne kan deretter importere fra 'your-lib' eller 'your-lib/utils' og få riktig format.

ESM bruker import/export og muliggjør tree-shaking. CJS bruker require() for kompatibilitet med Node.js. Lever begge formatene via exports-feltet i package.json, med betingelsene import/require. Eldre reserveordninger: main (CJS) og module (ESM). Bruk .mjs/.cjs-filendelser eller type: module for å markere formatet eksplisitt. Test begge formatene med node CLI etter byggingen. Vær oppmerksom på faren ved dual package når du har singleton-tilstand.