Modules JavaScript : import, export et ESM

Quand un fichier JavaScript grossit, tout le monde finit par avoir le même réflexe : « il faut découper ». Les ES modules (ESM) sont la façon standard de le faire en JavaScript moderne. Comprendre import et export, ce que le navigateur et Node.js en font, et pourquoi un bundler intervient encore, change réellement la maintenabilité d’un projet.

Ce guide reste pédagogique : assez de théorie pour ne pas naviguer à vue, assez de pratique pour ouvrir votre éditeur dès demain.

Un module, c’est quoi ?

Un module est un fichier JavaScript qui déclare clairement ce qu’il expose au reste du projet et ce qu’il consomme ailleurs. Au lieu d’empiler des scripts globaux qui se marchent dessus, chaque fichier possède une frontière.

Avec les ES modules :

• vous exportez des fonctions, constantes ou classes avec export ;
• vous importez ce dont vous avez besoin avec import ;
• chaque module a son propre périmètre (scope) : plus de pollution accidentelle de l’objet window ;
• les dépendances sont explicites et se lisent en tête de fichier.

Avant les modules, on utilisait des fonctions auto-invoquées, des espaces de noms maison, puis CommonJS (require et module.exports) côté Node.js. Aujourd’hui, ESM est le standard du langage. CommonJS reste présent dans de nombreux paquets npm historiques, d’où quelques frictions. Le guide MDN sur les modules fait référence.

Pourquoi découper change un projet

Lisibilité

Un fichier utils.js de plusieurs milliers de lignes devient illisible. Des modules date.js, format.js et api/client.js racontent une histoire, et un nouvel arrivant trouve plus vite où intervenir.

Réutilisation

Exporter une fonction pure comme formatPrice(amount, locale) évite de la recopier dans trois pages, donc d’obtenir trois versions qui divergent.

Tests

Tester une fonction exportée est simple. Tester un script qui modifie des variables globales et touche au DOM dès son chargement l’est beaucoup moins.

Collaboration

Deux personnes peuvent travailler sur des modules distincts avec moins de conflits Git, à condition de respecter les frontières et d’éviter les imports circulaires.

Performance, avec nuance

Les modules permettent le tree-shaking : l’outil de build élimine le code inutilisé. En natif dans le navigateur, chaque fichier est une requête, d’où le rôle des bundlers en production. En développement, des outils comme Vite exploitent au contraire le découpage ESM pour un rechargement rapide.

Syntaxe essentielle : export et import

Exports nommés

// math.js
export function add(a, b) {
  return a + b;
}

export const PI = 3.14159;

// app.js
import { add, PI } from './math.js';

console.log(add(2, 3), PI);

Les accolades ne sont pas du destructuring : elles ciblent des exports nommés, et le nom doit correspondre (sauf alias). La page MDN sur export et celle sur import détaillent toutes les variantes.

Export par défaut

// Button.js
export default function Button(label) {
  const btn = document.createElement('button');
  btn.textContent = label;
  return btn;
}

import Button from './Button.js';

Un module ne peut avoir qu’un seul export default. C’est pratique pour un composant principal ; pour des utilitaires, les exports nommés sont préférables, car l’auto-complétion les découvre mieux.

Alias, import global et réexport

import { add as somme } from './math.js';
import * as math from './math.js';

math.add(1, 2);

Pour exposer une API publique depuis un dossier, un fichier d’index réexporte le nécessaire :

// components/index.js
export { default as Button } from './Button.js';
export { Card } from './Card.js';

Le reste du projet importe depuis ./components/index.js sans connaître l’arborescence interne.

Navigateur, Node.js et bundlers

Dans le navigateur

Pour activer ESM dans une page :

<script type="module" src="/js/app.js"></script>

Quelques points importants, détaillés dans la page MDN de l’élément script :

1. les modules sont différés par défaut, comme avec l’attribut defer ;
2. les chemins d’import sont des URL relatives ou absolues (./lib.js, /js/lib.js) ;
3. l’extension .js est en général obligatoire en natif ;
4. la politique CORS s’applique : ouvrir la page en file:// casse souvent les imports, utilisez un petit serveur local.

Un exemple minimal :

// app.js
import { greet } from './greet.js';

document.querySelector('#sortie').textContent = greet('Léa');

Pour comprendre ce qui se passe à l’exécution, lisez Comment fonctionne JavaScript dans le navigateur.

Avec Node.js

Node.js active ESM de deux façons : avec "type": "module" dans package.json, ou avec l’extension .mjs. CommonJS reste le comportement historique de nombreux projets, et mélanger les deux demande de la rigueur (imports dynamiques, paquets publiés dans les deux formats).

// Node.js en ESM
import fs from 'node:fs/promises';
import { config } from './config.js';

Beaucoup de nouveaux projets partent directement en ESM, tandis que les bases de code anciennes migrent progressivement.

Pourquoi les bundlers existent encore

Si le navigateur comprend les modules, pourquoi Webpack, Rollup, esbuild ou Vite ?

• trop de petits fichiers peuvent coûter en latence réseau, un point moins critique avec HTTP/2 et HTTP/3 mais jamais nul ;
• la transpilation de TypeScript, JSX ou de syntaxes récentes ;
• l'optimisation : minification, tree-shaking, découpage du code, empreintes de cache ;
• la compatibilité avec des paquets npm qui ne sont pas toujours prêts pour le navigateur.

En pratique, vous écrivez en modules et l’outil produit les fichiers adaptés à la production.

ESM, CommonJS et TypeScript

• ESM : standard du langage, syntaxe import et export.
• CommonJS : écosystème Node.js historique, avec require.
• TypeScript : compile vers l’un ou l’autre selon les options module et moduleResolution.

Inutile de tout maîtriser dès le premier jour. Commencez par ESM dans un petit projet front, puis explorez Node.js et TypeScript quand le besoin apparaît.

Cas concret : d’un script unique à des modules

Imaginez une page produit avec un seul product.js de plusieurs centaines de lignes : carrousel, avis, ajout au panier, mesure d’audience. Un découpage raisonnable :

product/
  carousel.js
  reviews.js
  cart.js
  tracking.js
  main.js

Le fichier main.js orchestre :

import { initCarousel } from './carousel.js';
import { initReviews } from './reviews.js';
import { bindAddToCart } from './cart.js';

initCarousel(document.querySelector('[data-carousel]'));
initReviews(document.querySelector('[data-reviews]'));
bindAddToCart(document.querySelector('[data-add-cart]'));

Chaque module expose une fonction d’initialisation claire. Vous pouvez désactiver le suivi en retirant un import, tester le carrousel isolément, et éviter qu’une variable index du carrousel n’écrase celle des avis. Pour manipuler les éléments de la page dans chaque module, voyez DOM JavaScript : manipuler la page correctement.

Si ce JavaScript est devenu une boule de neige sur un site existant, un audit de performance et de qualité aide à prioriser le découpage.

Erreurs fréquentes

• Oublier type="module" : sans cet attribut, import provoque une erreur dont le message parle souvent de « token inattendu » plutôt que de modules.
• Chemins incorrects : import x from 'math.js' cherche un paquet, pas un fichier voisin. Pour un fichier local, préfixez par ./ ou ../.
• Extensions manquantes : from './math' fonctionne souvent avec un bundler, pas en ESM natif.
• Imports circulaires : A importe B qui importe A. Cela peut sembler marcher, jusqu’au jour où une valeur est undefined au mauvais moment. Extrayez un troisième module partagé.
• Tout mettre en export par défaut : les noms deviennent libres à chaque import. Les exports nommés documentent mieux l’API.
• Mélanger les conventions : CommonJS ici, ESM là, variables globales ailleurs. Choisissez une convention par paquet et documentez-la.

Bonnes pratiques

• Une responsabilité par module, sans extrême : ni fichier-monstre, ni micro-module de trois lignes partout. Visez des unités que vous pouvez nommer en une phrase.
• Une API publique stable : ce que vous exportez est un contrat. Ajoutez plutôt que de renommer, ou versionnez consciemment.
• Pas d’effet de bord au chargement : un module qui lance un fetch ou modifie le DOM dès l’import surprend. Exportez des fonctions et appelez-les depuis un main.
• Imports statiques d’abord : ils sont analysables par les outils. Gardez import() pour le chargement différé réel (routes, fenêtres modales lourdes).
• Des noms explicites : utils.js attire tout, formatCurrency.js guide.
• Un point d’entrée documenté dans le README (main.js, index.js).

Conclusion

Un module JavaScript (ES module) est un fichier aux frontières explicites : export ce que vous offrez, import ce que vous consommez. Ce modèle améliore la lisibilité, les tests, la collaboration et, avec le bon outillage, la livraison.

Commencez petit : découpez un script monolithique en trois modules à responsabilité claire, branchez-les avec type="module" et observez le confort gagné. Ajoutez ensuite un bundler ou TypeScript si le projet le justifie. Pour consolider les bases, relisez Variables, fonctions et objets en JavaScript puis l’asynchrone en JavaScript. Pour suivre un parcours complet, rejoignez Academy Yunt.

FAQ

Les modules remplacent-ils les frameworks ?

Non. React, Vue et les autres s’appuient sur les modules. ESM organise le code ; le framework organise l’interface et l’état.

Faut-il un bundler pour apprendre ?

Pas au début : un serveur local et type="module" suffisent. Le bundler devient utile avec TypeScript, JSX ou pour optimiser la production.

L’instruction import est-elle asynchrone ?

Le chargement des modules est géré par l’environnement : le code situé après un import statique s’exécute quand les dépendances sont prêtes. L'import() dynamique, lui, renvoie une promesse.

Peut-on utiliser des modules sans npm ?

Oui, en front pur. npm devient pertinent dès que vous réutilisez des paquets tiers.

Pourquoi mon import échoue-t-il encore avec Node.js ?

Vérifiez "type": "module", les extensions de fichiers et le format du paquet visé (ESM ou CommonJS). Le message d’erreur indique souvent le conflit.