À propos de ce cours
Cette leçon présente les modules ES, le système de modules standard de JavaScript, recommandé pour les nouveaux projets Node.js. Elle montre comment les activer ("type": "module" ou extension .mjs), écrire des exports nommés et un export par défaut, et utiliser toutes les formes d'import, y compris l'import dynamique. Les règles propres aux modules ES sont détaillées : extension obligatoire, import.meta.dirname et import.meta.filename, import de JSON avec with { type: 'json' }, top-level await et liaisons en lecture seule. La cohabitation avec CommonJS (import par défaut d'un module CJS, require() d'un module ES) est expliquée, avec un tableau comparatif, deux activités corrigées et un quiz.
Objectifs
- Activer les modules ES dans un projet Node.js.
- Utiliser les exports nommés, l'export par défaut et les différentes formes d'
import. - Remplacer
__dirname,require()d'un JSON et le chargement conditionnel par leurs équivalents ES. - Faire cohabiter modules ES et CommonJS, et choisir le bon système.
Présentation des modules ES
- Les modules ES (ECMAScript modules, ou ESM) sont le système de modules standard du langage JavaScript, introduit en 2015. Ce sont les mêmes
importetexportque dans le navigateur, dans React, Angular ou Vue. - Node.js les prend entièrement en charge. Pour un nouveau projet, c'est le choix recommandé, et celui de la suite de ce cours.
- Deux façons de les activer :
- ajouter
"type": "module"danspackage.json: tous les fichiers.jsdu projet deviennent des modules ES (npm pkg set type=module) ; - ou nommer un fichier avec l'extension
.mjs, qui est toujours un module ES.
- ajouter
- Les modules ES (ECMAScript modules, ou ESM) sont le système de modules standard du langage JavaScript, introduit en 2015. Ce sont les mêmes
Exporter
- Le mot-clé
exportse place devant ce que l'on veut partager. Il existe deux sortes d'exports :- les exports nommés: autant que l'on veut, chacun avec son nom ;
- l'export par défaut (
export default) : un seul par module, en général l'élément principal.
// outils.js : un module ES export const TVA = 0.19; export function prixTTC(prixHT) { return Math.round(prixHT * (1 + TVA) * 100) / 100; } export default function formaterPrix(montant) { return `${montant.toFixed(2)} DT`; }- Le mot-clé
- On peut aussi déclarer d'abord, puis exporter en une ligne à la fin du fichier :
export { TVA, prixTTC };, éventuellement en renommant :export { prixTTC as calculerTTC };. Importer
- Le fichier suivant montre toutes les formes d'
import:
// app.js : importe le module outils.js import formaterPrix, { prixTTC, TVA } from './outils.js'; import * as outils from './outils.js'; import { readFile } from 'node:fs/promises'; import config from './config.json' with { type: 'json' }; console.log(formaterPrix(prixTTC(100))); console.log(`TVA : ${TVA * 100} %`, Object.keys(outils)); console.log(`Ce fichier : ${import.meta.filename}`); console.log(`Son dossier : ${import.meta.dirname}`); // await au premier niveau du module : pas besoin de fonction async const texte = await readFile(new URL('./config.json', import.meta.url), 'utf8'); console.log(JSON.parse(texte).nom, config.port); // import dynamique : charger un module seulement quand on en a besoin if (process.argv.includes('--details')) { const os = await import('node:os'); console.log(`Système : ${os.platform()}`); }node app.js --details 119.00 DT TVA : 19 % [ 'TVA', 'default', 'prixTTC' ] Ce fichier : C:\Projets\esm\app.js Son dossier : C:\Projets\esm boutique 3000 Système : win32Forme Ce qui est importé import formaterPrix from './outils.js'L'export par défaut, sous le nom que l'on choisit import { prixTTC, TVA } from './outils.js'Des exports nommés, avec leur nom exact import { prixTTC as ttc } from './outils.js'Un export nommé, renommé import * as outils from './outils.js'Tous les exports, rassemblés dans un objet import formaterPrix, { TVA } from './outils.js'L'export par défaut et des exports nommés const os = await import('node:os')Un module chargé à la demande (import dynamique) - Les
importstatiques s'écrivent en haut du fichier. Node.js les analyse avant d'exécuter le code : une faute dans un nom importé est signalée immédiatement, avant toute exécution. - L'import dynamique
await import(…)peut s'écrire n'importe où, par exemple dans unif. Il sert à charger un module seulement si on en a besoin.
- Le fichier suivant montre toutes les formes d'
Les règles propres aux modules ES
L'extension est obligatoire
- Pour vos fichiers, il faut écrire le chemin complet, extension comprise :
'./outils.js'. Sans l'extension, Node.js ne cherche pas le fichier :
Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'C:\Projets\esm\outils' imported from C:\Projets\esm\sans-ext.js- Pour vos fichiers, il faut écrire le chemin complet, extension comprise :
- Pour les modules natifs et les paquets npm, le nom suffit :
'node:fs/promises','dayjs'. import.meta remplace __dirname et __filename
import.meta.filenameetimport.meta.dirnamedonnent le chemin du fichier et de son dossier.import.meta.urldonne l'adresse du fichier sous la formefile:///…, utile pour construire un chemin relatif au fichier avecnew URL('./config.json', import.meta.url).
Importer un fichier JSON
- Il faut préciser qu'il s'agit de JSON avec
with { type: 'json' }:import config from './config.json' with { type: 'json' };
- Il faut préciser qu'il s'agit de JSON avec
await au premier niveau
- Dans un module ES, on peut écrire
awaitdirectement dans le fichier, hors de toute fonctionasync: c'est le top-level await. C'est pratique pour lire une configuration ou se connecter à une base de données au démarrage.
- Dans un module ES, on peut écrire
Le mode strict et les liaisons en lecture seule
- Un module ES est toujours en mode strict : une variable non déclarée provoque une erreur. Les noms importés sont en lecture seule :
TVA = 0.2dansapp.jsprovoqueTypeError: Assignment to constant variable. - Comme en CommonJS, un module n'est exécuté qu'une fois, puis mis en cache.
- Un module ES est toujours en mode strict : une variable non déclarée provoque une erreur. Les noms importés sont en lecture seule :
Faire cohabiter ES et CommonJS
Importer un module CommonJS dans un module ES
- Un module ES peut importer un module CommonJS ou un ancien paquet npm. L'import par défaut renvoie
module.exportset fonctionne toujours :
// ancien.cjs : un module CommonJS dans un projet ES module.exports = { saluer: (nom) => `Bonjour ${nom}` };// mixte.js : importer un module CommonJS depuis un module ES import ancien from './ancien.cjs'; // l'import par défaut fonctionne toujours const { saluer } = ancien; console.log(saluer('Ali'));- Un module ES peut importer un module CommonJS ou un ancien paquet npm. L'import par défaut renvoie
- Les imports nommés, comme
import { saluer } from './ancien.cjs', ne fonctionnent que si Node.js parvient à détecter les noms exportés en analysant le fichier. Ici, il n'y parvient pas : - Le message propose lui-même la solution : import par défaut, puis déstructuration.
Charger un module ES depuis CommonJS
- Depuis Node.js 22.12 (et 20.19),
require()peut charger un module ES, s'il n'utilise pas de top-level await. L'export par défaut est alors dans la propriétédefault:
// requiert-esm.cjs : require() d'un module ES (Node.js 22.12 et plus, 20.19 et plus) const outils = require('./outils.js'); console.log(outils.prixTTC(50), outils.default(10));node requiert-esm.cjs 59.5 10.00 DT- Depuis Node.js 22.12 (et 20.19),
- Avec une version plus ancienne de Node.js, il faut l'import dynamique :
const outils = await import('./outils.js'), dans une fonctionasync. - Certains paquets récents ne sont plus publiés qu'en module ES, par exemple
chalkdepuis la version 5. C'est une raison de plus de démarrer les nouveaux projets en ES.
SyntaxError: Named export 'saluer' not found. The requested module './ancien.cjs' is a CommonJS module, which may not support all module.exports as named exports. CommonJS modules can always be imported via the default export, for example using: import pkg from './ancien.cjs'; const { saluer } = pkg;Comparaison des deux systèmes
Activité 1 : convertir en modules ES
- Convertissez ce projet CommonJS en modules ES, sans changer son comportement.
// panier.js const { prixTTC } = require('./outils'); class Panier { #articles = []; ajouter(nom, prixHT) { this.#articles.push({ nom, prixHT }); } total() { return this.#articles.reduce((s, a) => s + prixTTC(a.prixHT), 0); } } module.exports = Panier; // index.js const path = require('node:path'); const Panier = require('./panier'); const p = new Panier(); p.ajouter('Clavier', 50); p.ajouter('Souris', 20); console.log(p.total(), path.basename(__filename));Voir le corrigé
npm pkg set type=module// outils.js : remplacer module.exports par des export (voir la leçon) // panier.js import { prixTTC } from './outils.js'; export default class Panier { #articles = []; ajouter(nom, prixHT) { this.#articles.push({ nom, prixHT }); } total() { return this.#articles.reduce((s, a) => s + prixTTC(a.prixHT), 0); } } // index.js import path from 'node:path'; import Panier from './panier.js'; const p = new Panier(); p.ajouter('Clavier', 50); p.ajouter('Souris', 20); console.log(p.total(), path.basename(import.meta.filename)); // 83.3 index.jsLes quatre changements :
"type": "module",importau lieu derequire, l'extension.jsdans les chemins, etimport.meta.filenameà la place de__filename.Activité 2 : trouver les erreurs
- Dans un projet
"type": "module", chacune de ces lignes provoque une erreur. Expliquez pourquoi et corrigez.
import { formaterPrix } from './outils.js'; // 1 (formaterPrix est l'export par défaut) import { TVA } from './outils'; // 2 import config from './config.json'; // 3 const chemin = __dirname + '/donnees'; // 4 const fs = require('node:fs'); // 5Voir le corrigé
- Un export par défaut s'importe sans accolades :
import formaterPrix from './outils.js'; - L'extension manque :
import { TVA } from './outils.js'; - Il faut préciser le type :
import config from './config.json' with { type: 'json' }; __dirnamen'existe pas en ES :const chemin = path.join(import.meta.dirname, 'donnees');requiren'existe pas en ES :import fs from 'node:fs';
- Dans un projet
À retenir
- Les modules ES sont le standard JavaScript ; on les active avec
"type": "module"ou l'extension.mjs. exportpour les exports nommés,export defaultpour l'export principal ; on les importe respectivement avec et sans accolades.- L'extension des fichiers est obligatoire dans les
import. import.meta.dirnameremplace__dirname; JSON avecwith { type: 'json' };awaitpossible au premier niveau ;await import()pour charger à la demande.- Un module CommonJS s'importe toujours par l'import par défaut ;
require()charge un module ES depuis Node.js 22.12.
- Les modules ES sont le standard JavaScript ; on les active avec
Testez-vous
- 1. Combien d'exports par défaut un module peut-il avoir ?
- 2. Que contient
outilsaprèsimport * as outils from './outils.js'? - 3. Dans un projet
"type": "module", comment écrire un fichier CommonJS ? - 4. Pourquoi peut-on écrire
awaitdirectement dans un module ES ? - Un seul.
- Un objet qui rassemble tous les exports :
TVA,prixTTCet l'export par défaut, sous le nomdefault. - En lui donnant l'extension
.cjs. - Parce que les modules ES sont chargés de façon asynchrone : Node.js peut attendre la fin de l'
awaitavant de terminer le chargement du module (top-level await).
Voir les réponses
| CommonJS | Modules ES | |
|---|---|---|
| Activation | Par défaut, ou .cjs | "type": "module", ou .mjs |
| Exporter | module.exports = { … } | export, export default |
| Importer | const x = require('./x') | import x from './x.js' |
| Extension du fichier | Facultative | Obligatoire |
| Chargement | Synchrone, au moment du require() | Analysé avant l'exécution ; asynchrone |
| Chemin du fichier | __filename, __dirname | import.meta.filename, import.meta.dirname |
| JSON | require('./config.json') | import … with { type: 'json' } |
| await au premier niveau | Non | Oui |
| Navigateur | Non | Oui : même syntaxe |
Cet article vous a-t-il aidé ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !