Modules ES contre CommonJS dans Node.js

Ce que c'est

CommonJS (CJS) est le système de modules d'origine de Node : require() charge de façon synchrone à l'exécution et un module exporte tout ce qu'il assigne à module.exports. Les modules ES (ESM) sont le standard du langage : import et export sont statiques, résolus avant l'exécution du corps du module, le chargement est asynchrone, le await de premier niveau est autorisé, et import.meta porte les métadonnées du module. Node décide par fichier : .mjs est toujours ESM, .cjs toujours CJS, et .js suit le champ "type" du package.json le plus proche. En l'absence de champ "type", la documentation des paquets qualifie le fichier d'ambigu : les versions actuelles de Node l'exécutent d'abord comme CommonJS et, si l'analyseur trouve une syntaxe de module ES, le réévaluent comme module ES (détection de syntaxe) ; les versions plus anciennes le traitent simplement comme CommonJS. La documentation ESM liste ce qui manque en ESM (require, module.exports, __filename, __dirname) et les remplacements : import.meta.filename, import.meta.dirname, import.meta.resolve() et module.createRequire(). ESM peut importer du CommonJS (l'import par défaut est module.exports), et les versions actuelles de Node peuvent faire un require() d'un module ES tant que son graphe ne contient aucun await de premier niveau.

Pourquoi c'est important

Le mélange des deux systèmes est à l'origine des erreurs de démarrage les plus fréquentes dans les projets Node : « Cannot use import statement outside a module », ERR_REQUIRE_ESM, exports is not defined. Les lanceurs de tests, la sortie de TypeScript et les empaqueteurs ont chacun leur propre réglage de modules, et une incohérence échoue à l'exécution plutôt qu'à la compilation.

Comment l'appliquer

• Nouveau code : définir "type": "module" dans package.json et écrire de l'ESM partout ; nommer en .cjs les quelques fichiers qui doivent rester en CommonJS.
• Les imports relatifs en ESM doivent inclure l'extension du fichier (./util.js, ./dir/index.js) ; le résolveur ne devine pas.
• Le JSON s'importe avec un attribut : import cfg from "./cfg.json" with { type: "json" }.
• Bibliothèques livrant les deux formats : déclarer "exports" avec les conditions import et require, et lire au préalable la documentation des paquets ainsi que le dépôt d'exemples qu'elle référence sur les paquets doubles ; un paquet chargé par les deux points d'entrée existe deux fois, avec un état de module distinct (le risque du paquet double).
• Dans les navigateurs, les scripts de module doivent être servis avec un type MIME JavaScript tel que text/javascript ; MDN documente l'erreur de vérification stricte du type MIME pour les fichiers .mjs servis autrement.

Pièges

Les imports circulaires se comportent différemment : les liaisons ESM sont actives mais peuvent être non initialisées si elles sont lues trop tôt. Un require() d'un module ES utilisant un await de premier niveau lève ERR_REQUIRE_ASYNC_MODULE ; utiliser import() à la place. Un compilateur qui émet des appels require dans un paquet "type": "module" produit un code qui échoue au chargement ; garder le réglage de sortie de modules du compilateur aligné sur celui de l'environnement d'exécution.