Formations — 1 037 leçons en français

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. import et export, analysés avant toute exécution. C'est le format d'un projet Node neuf.

CommonJS

Le format historique de Node. require et module.exports, résolus à l'exécution. Encore majoritaire dans les paquets publiés.

`"type": "module"`

Le champ de package.json qui dit à Node de lire les .js du dossier comme des modules ES. Sans lui, ils sont lus en CommonJS.

Import statique

import n'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 un require depuis 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 .js que CommonJS ajoutait.

Lire l'explication détaillée et faire le quiz →

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.