Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
Laravel

Les modules ES : import et export dans Node.js

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), é...

0 chapitres 0 QCM Accès gratuit
Dans cet article

À 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.
  1. 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.
  2. 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 import et export que 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" dans package.json: tous les fichiers .js du projet deviennent des modules ES (npm pkg set type=module) ;
      • ou nommer un fichier avec l'extension .mjs, qui est toujours un module ES.
    Comparaison des modules CommonJS et des modules ES dans Node.js
  3. Exporter

    • Le mot-clé export se 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`;
    }
  4. 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 };.
  5. 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 : win32
    FormeCe 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 import statiques 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 un if. Il sert à charger un module seulement si on en a besoin.
  6. Les règles propres aux modules ES

    1. 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
    2. Pour les modules natifs et les paquets npm, le nom suffit : 'node:fs/promises', 'dayjs'.
    3. import.meta remplace __dirname et __filename
      • import.meta.filename et import.meta.dirname donnent le chemin du fichier et de son dossier. import.meta.url donne l'adresse du fichier sous la forme file:///…, utile pour construire un chemin relatif au fichier avec new URL('./config.json', import.meta.url).
    4. 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' };
    5. await au premier niveau
      • Dans un module ES, on peut écrire await directement dans le fichier, hors de toute fonction async: c'est le top-level await. C'est pratique pour lire une configuration ou se connecter à une base de données au démarrage.
    6. 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.2 dans app.js provoque TypeError: Assignment to constant variable.
      • Comme en CommonJS, un module n'est exécuté qu'une fois, puis mis en cache.
  7. Faire cohabiter ES et CommonJS

    1. 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.exports et 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'));
    2. 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 :
    3. 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;
    4. Le message propose lui-même la solution : import par défaut, puis déstructuration.
    5. 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
    6. Avec une version plus ancienne de Node.js, il faut l'import dynamique : const outils = await import('./outils.js'), dans une fonction async.
    7. Certains paquets récents ne sont plus publiés qu'en module ES, par exemple chalk depuis la version 5. C'est une raison de plus de démarrer les nouveaux projets en ES.
  8. Comparaison des deux systèmes

  9. CommonJSModules ES
    ActivationPar défaut, ou .cjs"type": "module", ou .mjs
    Exportermodule.exports = { … }export, export default
    Importerconst x = require('./x')import x from './x.js'
    Extension du fichierFacultativeObligatoire
    ChargementSynchrone, au moment du require()Analysé avant l'exécution ; asynchrone
    Chemin du fichier__filename, __dirnameimport.meta.filename, import.meta.dirname
    JSONrequire('./config.json')import … with { type: 'json' }
    await au premier niveauNonOui
    NavigateurNonOui : même syntaxe
  10. 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.js

    Les quatre changements : "type": "module", import au lieu de require, l'extension .js dans les chemins, et import.meta.filename à la place de __filename.

  11. 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');                          // 5
    Voir le corrigé
    1. Un export par défaut s'importe sans accolades : import formaterPrix from './outils.js';
    2. L'extension manque : import { TVA } from './outils.js';
    3. Il faut préciser le type : import config from './config.json' with { type: 'json' };
    4. __dirname n'existe pas en ES : const chemin = path.join(import.meta.dirname, 'donnees');
    5. require n'existe pas en ES : import fs from 'node:fs';
  12. À retenir

    • Les modules ES sont le standard JavaScript ; on les active avec "type": "module" ou l'extension .mjs.
    • export pour les exports nommés, export default pour l'export principal ; on les importe respectivement avec et sans accolades.
    • L'extension des fichiers est obligatoire dans les import.
    • import.meta.dirname remplace __dirname; JSON avec with { type: 'json' }; await possible 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.
  13. Testez-vous

    • 1. Combien d'exports par défaut un module peut-il avoir ?
    • 2. Que contient outils après import * as outils from './outils.js'?
    • 3. Dans un projet "type": "module", comment écrire un fichier CommonJS ?
    • 4. Pourquoi peut-on écrire await directement dans un module ES ?
    • Voir les réponses
      1. Un seul.
      2. Un objet qui rassemble tous les exports : TVA, prixTTC et l'export par défaut, sous le nom default.
      3. En lui donnant l'extension .cjs.
      4. Parce que les modules ES sont chargés de façon asynchrone : Node.js peut attendre la fin de l'await avant de terminer le chargement du module (top-level await).

Cet article vous a-t-il aidé ?