Accueil › Node.js › Modules ES et CommonJS
Modules ES et CommonJS
Modules et npmdebutant
Node sait lire deux formats de modules. Un projet neuf en choisit un et s'y tient.
Déclarer le format
{
"name": "mon-api",
"type": "module"
}
Sans ce champ, un fichier .js est lu en CommonJS et le mot-clé import y
est une erreur de syntaxe. Avec lui, tous les .js du dossier sont des
modules ES.
| Fichier | Format |
|---|---|
.mjs |
module ES, toujours |
.cjs |
CommonJS, toujours |
.js |
selon le type du package.json le plus proche |
L'extension n'est plus optionnelle
import { creerServeur } from "./serveur.js"; // ✅
import { creerServeur } from "./serveur"; // ⛔ ERR_MODULE_NOT_FOUND
CommonJS ajoutait .js tout seul, essayait /index.js, testait plusieurs
extensions. Les modules ES ne devinent rien : un chemin relatif est un chemin,
extension comprise. Les noms de paquets, eux, restent sans extension.
import n'est pas un appel de fonction
if (production) import "./debug.js"; // ⛔ erreur de syntaxe
Les import sont hissés : Node construit le graphe complet et évalue les
dépendances avant la première ligne du fichier. On ne peut donc pas importer
conditionnellement, ni calculer un chemin.
const outils = await import(`./outils-${process.platform}.js`); // ✅
L'import dynamique est, lui, un appel ordinaire qui rend une promesse. Il est la seule forme conditionnelle — et il sait charger du CommonJS.
Les termes à connaître
- Module ES
Le format standard du langage.
importetexport, analysés avant toute exécution. C'est le format d'un projet Node neuf.- CommonJS
Le format historique de Node.
requireetmodule.exports, résolus à l'exécution. Encore majoritaire dans les paquets publiés.- `"type": "module"`
Le champ de
package.jsonqui dit à Node de lire les.jsdu dossier comme des modules ES. Sans lui, ils sont lus en CommonJS.- Import statique
importn'est pas un appel de fonction. Il est hissé, exécuté avant le reste du fichier, et ne peut pas être conditionnel.- Import dynamique
await import("...")— la seule forme conditionnelle. Rend une promesse, fonctionne dans les deux formats, et sait charger du CommonJS.- createRequire
createRequire(import.meta.url)fabrique unrequiredepuis un module ES. Le pont utile pour un paquet CommonJS sans export nommé.- `ERR_MODULE_NOT_FOUND`
L'erreur d'un chemin relatif sans extension en modules ES. Le format ne devine pas le
.jsque CommonJS ajoutait.
Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.