Podwójny wynik pakietu ESM i CJS

ESM (ECMAScript Modules) to oficjalny standard modułów JavaScript wykorzystujący składnię import i export. ESM można analizować statycznie — bundlery mogą określić podczas kompilowania, które eksporty są dokładnie używane, co umożliwia tree-shaking. Nowoczesne przeglądarki i Node.js natywnie obsługują ESM.

CJS (CommonJS) wykorzystuje składnię require() i module.exports. Był to oryginalny system modułów Node.js i nadal jest potrzebny do zapewnienia zgodności ze starszymi środowiskami Node.js, z Jest (który historycznie używał CJS) oraz z kodem korzystającym z require(). CJS jest obliczany dynamicznie, co utrudnia tree-shaking.

Nowoczesny pakiet npm powinien zawierać zarówno ESM, jak i CJS, aby zapewnić maksymalną zgodność. Odbiorcy ESM (Vite, Next.js i nowoczesne bundlery) otrzymują importy obsługujące tree-shaking. Odbiorcy CJS (starsze skrypty Node.js oraz Jest bez konfiguracji) otrzymują zgodność z require(). Pole exports w package.json informuje Node i bundlery, którego formatu użyć.

Pole exports w package.json to nowoczesny sposób definiowania warunkowych punktów wejścia. Przykład: { '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }. Bundlery i Node.js 12+ odczytują exports, aby automatycznie wybrać właściwy format.

Starsze narzędzia nie rozumieją pola exports. Aby zapewnić zgodność, ustaw także: main wskazujące na wynik CJS (zapasowa ścieżka require dla starszego Node) oraz module wskazujące na wynik ESM (wskazówka dla webpack/rollup; rozwiązanie niestandardowe, ale szeroko obsługiwane). Nowoczesne narzędzia preferują exports, a starsze korzystają z zapasowych pól main/module.

Ustawienie "type": "module" w package.json powoduje, że wszystkie pliki .js w pakiecie są traktowane jako ESM. Jeśli dostarczasz oba formaty, potrzebujesz wtedy jawnych rozszerzeń: użyj .mjs dla plików ESM i .cjs dla plików CJS, gdy type to module, lub odwrotnie. tsup obsługuje to automatycznie.

Użycie rozszerzeń plików .mjs (ESM) i .cjs (CJS) jawnie określa format niezależnie od pola type. Eliminuje to niejednoznaczność. tsup może wygenerować: index.js (ESM) i index.cjs (CJS), gdy format to ['esm', 'cjs'] i nie ustawiono pola type, zgodnie z najczęściej stosowaną konwencją.

Gdy pakiet udostępnia zarówno format ESM, jak i CJS, bundler odbiorcy może załadować obie wersje w tym samym procesie — na przykład wersję ESM dla głównej aplikacji i wersję CJS dla testu Jest. Jeśli pakiet ma stan na poziomie modułu, taki jak kontekst React, obie instancje mają niezależny stan. To właśnie zagrożenie pakietu dwupostaciowego.

Aby ograniczyć to zagrożenie: nie przechowuj stanu na poziomie modułu w bibliotece (unikaj wzorców singleton), precyzyjnie używaj warunków exports, aby mieć pewność, że zostanie załadowany tylko jeden format, oraz udokumentuj, że testy powinny konfigurować bundler tak, aby używał ESM. Zagrożenie dotyczy głównie bibliotek korzystających ze współdzielonych singletonów.

Po zbudowaniu sprawdź działanie obu formatów. 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)". Oba formaty powinny zostać rozwiązane bez błędów przed opublikowaniem pakietu.

Pole exports obsługuje wiele punktów wejścia: { '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }. Odbiorcy mogą wtedy importować z 'your-lib' lub 'your-lib/utils' i otrzymają właściwy format.

Jaki jest główny cel pola exports w pliku package.json biblioteki?

ESM wykorzystuje import/export i umożliwia tree-shaking. CJS wykorzystuje require() w celu zapewnienia zgodności z Node.js. Dostarczaj oba formaty za pośrednictwem pola exports w package.json, używając warunków import/require. Starsze rozwiązania zapasowe to main (CJS) i module (ESM). Używaj rozszerzeń .mjs/.cjs lub type: module, aby jawnie oznaczyć format. Po zbudowaniu testuj oba formaty za pomocą interfejsu wiersza poleceń node. Uważaj na zagrożenie pakietu dwupostaciowego w przypadku stanu singletonów.