Sortie de paquet double ESM et CJS

ESM (modules ECMAScript) est la norme officielle des modules JavaScript qui utilise la syntaxe import et export. ESM peut être analysé statiquement : les outils de regroupement peuvent déterminer au moment de la compilation quelles exportations sont exactement utilisées, ce qui permet d’éliminer le code inutilisé. Les navigateurs modernes et Node.js prennent tous deux ESM en charge nativement.

CJS (CommonJS) utilise la syntaxe require() et module.exports. Il s’agissait du système de modules d’origine de Node.js et il reste nécessaire pour assurer la compatibilité avec les anciens environnements Node.js, Jest (qui utilisait historiquement CJS) et le code qui utilise require(). CJS est évalué dynamiquement, ce qui rend l’élimination du code inutilisé plus difficile.

Un paquet npm moderne devrait fournir à la fois ESM et CJS afin de maximiser la compatibilité. Les utilisateurs d’ESM (Vite, Next.js et les outils de regroupement modernes) bénéficient d’importations dont le code inutilisé peut être éliminé. Les utilisateurs de CJS (anciens scripts Node.js et Jest sans configuration) bénéficient de la compatibilité avec require(). Le champ exports de package.json indique à Node et aux outils de regroupement quel format utiliser.

Le champ exports de package.json est la méthode moderne pour définir des points d’entrée conditionnels. Exemple : { '.': { 'import': './dist/esm/index.js', 'require': './dist/cjs/index.js', 'types': './dist/esm/index.d.ts' } }. Les outils de regroupement et Node.js lisent exports à partir de la version 12 de Node.js pour sélectionner automatiquement le format approprié.

Les anciens outils ne comprennent pas le champ exports. Pour assurer la compatibilité, définissez également : main pointant vers la sortie CJS (solution de repli pour require de Node), et module pointant vers la sortie ESM (indication pour webpack/Rollup, non standard mais largement prise en charge). Les outils modernes privilégient exports ; les anciens outils se replient sur main/module.

La définition de "type": "module" dans package.json fait que tous les fichiers .js du paquet sont traités comme des fichiers ESM. Si vous fournissez deux formats, vous devez alors utiliser des extensions explicites : utilisez .mjs pour les fichiers ESM et .cjs pour les fichiers CJS lorsque type vaut module, ou l’inverse. tsup gère cela automatiquement.

L’utilisation explicite des extensions de fichier .mjs (ESM) et .cjs (CJS) indique le format indépendamment du champ type. Cela évite toute ambiguïté. tsup peut produire : index.js (ESM) et index.cjs (CJS) lorsque le format vaut ['esm', 'cjs'] et qu’aucun champ type n’est défini, conformément à la convention la plus courante.

Lorsqu’un paquet fournit à la fois les formats ESM et CJS, l’outil de regroupement d’un utilisateur peut charger les deux versions dans le même processus — par exemple la version ESM pour l’application principale et la version CJS pour une vérification Jest. Si le paquet possède un état au niveau du module (comme un contexte React), les deux instances ont un état indépendant. C’est le risque des paquets dans les deux formats.

Pour réduire ce risque : évitez l’état au niveau du module dans votre bibliothèque (pas de motifs d’instance unique), utilisez précisément les conditions de exports afin de garantir qu’un seul format est chargé et indiquez dans votre documentation que les vérifications doivent configurer leur outil de regroupement pour utiliser ESM. Ce risque concerne principalement les bibliothèques qui utilisent des instances uniques partagées.

Vérifiez que les deux formats fonctionnent après la compilation. Vérifiez le CJS : node -e "const lib = require('./dist/cjs/index.js'); console.log(lib)". Vérifiez l’ESM : node --input-type=module --eval "import { Component } from './dist/esm/index.js'; console.log(Component)". Les deux doivent se résoudre sans erreurs avant la publication.

Le champ exports prend en charge plusieurs points d’entrée : { '.': { import: './dist/esm/index.js', require: './dist/cjs/index.js' }, './utils': { import: './dist/esm/utils.js', require: './dist/cjs/utils.js' } }. Les utilisateurs importent ensuite depuis 'your-lib' ou 'your-lib/utils' et obtiennent le format approprié.

Quel est le rôle principal du champ exports dans le package.json d’une bibliothèque ?

ESM utilise import/export et permet d’éliminer le code inutilisé. CJS utilise require() pour assurer la compatibilité avec Node.js. Fournissez les deux formats via le champ exports de package.json, avec les conditions import/require. Solutions de repli anciennes : main (CJS) et module (ESM). Utilisez les extensions .mjs/.cjs ou type: module pour indiquer explicitement le format. Vérifiez les deux formats avec la CLI node après la compilation. Méfiez-vous du risque des paquets dans les deux formats lorsqu’ils utilisent un état d’instance unique.