Output duale dei pacchetti ESM e CJS

ESM (ECMAScript Modules) è lo standard ufficiale dei moduli JavaScript, che utilizza la sintassi import e export. ESM è analizzabile staticamente: i bundler possono determinare in fase di build esattamente quali export vengono utilizzati, abilitando il tree-shaking. I browser moderni e Node.js supportano entrambi ESM in modo nativo.

CJS (CommonJS) utilizza la sintassi require() e module.exports. Era il sistema di moduli originale di Node.js ed è ancora necessario per la compatibilità con gli ambienti Node.js meno recenti, con Jest (che storicamente utilizzava CJS) e con il codice che usa require(). CJS viene valutato dinamicamente, rendendo più difficile il tree-shaking.

Un pacchetto npm moderno dovrebbe pubblicare sia ESM sia CJS per massimizzare la compatibilità. I consumer ESM (Vite, Next.js e i bundler moderni) ottengono importazioni compatibili con il tree-shaking. I consumer CJS (gli script Node.js meno recenti e Jest senza configurazione) ottengono la compatibilità con require(). Il campo exports di package.json indica a Node e ai bundler quale formato utilizzare.

Il campo exports in package.json è il modo moderno per definire punti di ingresso condizionali. Esempio: { '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }. I bundler e Node.js 12+ leggono exports per selezionare automaticamente il formato corretto.

Gli strumenti meno recenti non comprendono il campo exports. Per garantire la compatibilità, imposti anche: main in modo che punti all'output CJS (fallback legacy per require di Node), e module in modo che punti all'output ESM (un'indicazione per webpack/rollup, non standard ma ampiamente supportata). Gli strumenti moderni preferiscono exports, mentre quelli legacy ripiegano su main/module.

Impostare "type": "module" in package.json fa sì che tutti i file .js del pacchetto vengano trattati come ESM. Se pubblica entrambi i formati, sono quindi necessarie estensioni esplicite: utilizzi .mjs per i file ESM e .cjs per i file CJS quando type è module, o viceversa. tsup gestisce automaticamente questo aspetto.

Usare esplicitamente le estensioni .mjs (ESM) e .cjs (CJS) indica il formato indipendentemente dal campo type. In questo modo si evita ogni ambiguità. tsup può generare: index.js (ESM) e index.cjs (CJS) quando format è ['esm', 'cjs'] e non è impostato alcun campo type, secondo la convenzione più comune.

Quando un pacchetto fornisce sia il formato ESM sia quello CJS, il bundler del consumer potrebbe caricare entrambe le versioni nello stesso processo, ad esempio la versione ESM per l'applicazione principale e la versione CJS per un test Jest. Se il pacchetto contiene stato a livello di modulo, come un contesto React, entrambe le istanze mantengono uno stato indipendente. Questo è il rischio del pacchetto duale.

Per mitigare questo rischio, eviti lo stato a livello di modulo nella libreria (nessun pattern singleton), utilizzi con precisione le condizioni di exports per assicurarsi che venga caricato un solo formato e documenti che i test devono configurare il proprio bundler per utilizzare ESM. Il rischio riguarda soprattutto le librerie con singleton condivisi.

Verifichi che entrambi i formati funzionino dopo la build. Per testare CJS: node -e "const lib = require('./dist/cjs/index.js'); console.log(lib)". Per testare ESM: node --input-type=module --eval "import { Component } from './dist/esm/index.js'; console.log(Component)". Entrambi devono essere risolti senza errori prima della pubblicazione.

Il campo exports supporta più entry point: { '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }. I consumer possono quindi importare da 'your-lib' o 'your-lib/utils' e ottenere il formato corretto.

Qual è lo scopo principale del campo exports nel package.json di una libreria?

ESM utilizza import/export e abilita il tree-shaking. CJS utilizza require() per la compatibilità con Node.js. Pubblichi entrambi tramite il campo exports di package.json, con le condizioni import/require. Fallback legacy: main (CJS) e module (ESM). Utilizzi le estensioni .mjs/.cjs o type: module per indicare esplicitamente il formato. Dopo la build, testi entrambi i formati con la CLI di node. Presti attenzione al rischio del pacchetto duale in presenza di stato singleton.