Les modules JavaScript

Ce guide aborde l'ensemble des notions vous permettant d'utiliser la syntaxe des modules en JavaScript.

Un peu de contexte

Les programmes JavaScript ont commencé par être assez petits, réalisant des tâches isolées uniquement là où l'interactivité était nécessaire. Après plusieurs années, nous avons maintenant des applications complètes qui sont exécutées dans les navigateurs avec des codes complexes et volumineux. Des programmes JavaScript sont également exécutés dans d'autres contextes (Node.js par exemple).

Il a donc été question de fournir un mécanisme pour diviser les programmes JavaScript en plusieurs modules qu'on pourrait importer les uns dans les autres. Cette fonctionnalité était présente dans Node.js depuis longtemps et plusieurs bibliothèques et frameworks JavaScript ont permis l'utilisation de modules (CommonJS, AMD, RequireJS ou, plus récemment, Webpack et Babel).

Bonne nouvelle, les navigateurs ont également commencé à prendre en charge ces fonctionnalités nativement. C'est le sujet de ce guide.

Cette implémentation permettra aux navigateurs d'optimiser le chargement des modules, rendant le fonctionnement plus efficace qu'une bibliothèque tierce avec un traitement côté client des allers-retours sur le réseau.

Compatibilité des navigateurs

L'utilisation des modules natifs JavaScript repose sur les instructions import and export dont vous pouvez voir l'état de la compatibilité ici :

import

Update compatibility data on GitHub
OrdinateurMobileServeur
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidFirefox pour AndroidOpera pour AndroidSafari sur iOSSamsung InternetNode.js
importChrome Support complet 61Edge Support complet 16
Support complet 16
Support complet 15
Désactivée
Désactivée From version 15: this feature is behind the Experimental JavaScript Features preference.
Firefox Support complet 60
Support complet 60
Aucun support 54 — 60
Désactivée
Désactivée From version 54 until version 60 (exclusive): this feature is behind the dom.moduleScripts.enabled preference. To change preferences in Firefox, visit about:config.
IE Aucun support NonOpera Support complet 47Safari Support complet 10.1WebView Android Support complet 61Chrome Android Support complet 61Firefox Android Support complet 60
Support complet 60
Aucun support 54 — 60
Désactivée
Désactivée From version 54 until version 60 (exclusive): this feature is behind the dom.moduleScripts.enabled preference. To change preferences in Firefox, visit about:config.
Opera Android Support complet 44Safari iOS Support complet 10.1Samsung Internet Android Aucun support Nonnodejs Support complet 8.5.0
Notes Désactivée
Support complet 8.5.0
Notes Désactivée
Notes files must have suffix .mjs, not .js
Désactivée From version 8.5.0: this feature is behind the --experimental-modules runtime flag.
Dynamic importChrome Support complet 63Edge Aucun support Non
Notes
Aucun support Non
Notes
Notes See development status.
Firefox Support complet 67
Support complet 67
Aucun support 66 — 67
Désactivée
Désactivée From version 66 until version 67 (exclusive): this feature is behind the javascript.options.dynamicImport preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE Aucun support NonOpera Support complet 50Safari Support complet 11.1WebView Android Support complet 63Chrome Android Support complet 63Firefox Android Support complet 67
Support complet 67
Aucun support 66 — 67
Désactivée
Désactivée From version 66 until version 67 (exclusive): this feature is behind the javascript.options.dynamicImport preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Support complet 46Safari iOS Support complet 11.1Samsung Internet Android Aucun support Nonnodejs ?

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Compatibilité inconnue  
Compatibilité inconnue
Voir les notes d'implémentation.
Voir les notes d'implémentation.
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.

export

Update compatibility data on GitHub
OrdinateurMobileServeur
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidFirefox pour AndroidOpera pour AndroidSafari sur iOSSamsung InternetNode.js
exportChrome Support complet 61Edge Support complet 16
Support complet 16
Support complet 15
Désactivée
Désactivée From version 15: this feature is behind the Experimental JavaScript Features preference.
Firefox Support complet 60
Support complet 60
Aucun support 54 — 60
Désactivée
Désactivée From version 54 until version 60 (exclusive): this feature is behind the dom.moduleScripts.enabled preference. To change preferences in Firefox, visit about:config.
IE Aucun support NonOpera Support complet 47Safari Support complet 10.1WebView Android Aucun support NonChrome Android Support complet 61Firefox Android Support complet 60
Support complet 60
Aucun support 54 — 60
Désactivée
Désactivée From version 54 until version 60 (exclusive): this feature is behind the dom.moduleScripts.enabled preference. To change preferences in Firefox, visit about:config.
Opera Android Support complet 44Safari iOS Support complet 10.1Samsung Internet Android Aucun support Nonnodejs ?

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Compatibilité inconnue  
Compatibilité inconnue
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.

Commençons par un exemple

Pour illustrer le fonctionnement des modules, nous avons créé un ensemble d'exemples disponibles sur GitHub. Ces exemples illustrent un ensemble de modules pour créer un élément <canvas> sur une page web puis dessiner (et afficher des informations) sur les différentes formes du canevas.

Ces opérations sont assez simples mais nous les avons choisies pour nous concentrer plutôt sur le fonctionnement des modules.

Note : Si vous souhaitez télécharger les exemples et les exécuter en local, vous devrez utiliser un serveur web local.

Structure de l'exemple

Dans notre premier exemple (cf. basic-modules), nous avons l'arborescence de fichier suivante :

index.html
main.js
modules/
    canvas.js
    square.js

Note : Tous les exemples de ce guide suivent la même structure.

Le répertoire dédié aux modules contient deux modules :

  • canvas.js — responsable de fonctions pour gérer le canevas
    • create() — crée un canevas avec les dimensions souhaitées (widthheight) à l'intérieur d'un élément <div> doté d'un identifiant et qui est ajouté à l'intérieur d'un élément indiqué. Cette fonction renvoie l'objet contenant le contexte du canevas et l'identifiant du conteneur.
    • createReportList() — crée une liste non ordonnée à l'intérieur d'un élément indiqué et dans lequel on affiche des données. Cette fonction renvoie l'identifiant de la liste.
  • square.js :
    • name — une constante qui est une chaîne de caractères : "square".
    • draw() — dessine un carré avec une taille/position/couleur données sur le canevas indiqué. Cette fonction renvoie un objet contenant la taille du carré, sa position et sa couleur.
    • reportArea() — écrit la surface d'un carré dans une liste donnée en fonction de la longueur de son côté.
    • reportPerimeter() — écrit le périmètre d'un carré dans une liste donnée en fonction de la longueur de son côté.

Exporter des fonctionnalités

Pour commencer et afin d'utiliser les fonctionnalités d'un module, on devra les exporter. Pour cela, on utilisera l'instruction export.

La méthode la plus simple consiste à placer cette instruction devant chaque valeur qu'on souhaite exporter, par exemple :

export const name = 'square';

export function draw(ctx, length, x, y, color) {
  ctx.fillStyle = color;
  ctx.fillRect(x, y, length, length);

  return {
    length: length,
    x: x,
    y: y,
    color: color
  };
}

Il est possible d'exporter des fonctions, des variables (qu'elles soient définies avec var, let ou const) et aussi des classes (que nous verrons par la suite). Les valeurs exportées doivent être présentes au plus haut niveau du script, il n'est pas possible d'utiliser export dans une fonction.

Une méthode plus concise consiste à exporter l'ensemble des valeurs grâce à une seule instruction située à la fin du fichier : les valeurs sont séparées par des virgules et la liste est délimitée entre accolades :

export { name, draw, reportArea, reportPerimeter };

Importer des fonctionnalités

Lorsque des fonctionnalités sont exportées par un premier module, on peut les importer dans un script afin de les utiliser. Voici la méthode la plus simple pour ce faire :

import { name, draw, reportArea, reportPerimeter } from './modules/square.js';

On utilise ici l'instruction import, suivi d'une liste d'identifiants séparées par des virgules et délimitée par des accolades, suivie du mot-clé from puis du chemin vers le fichier du module. Le chemin est relatif à la racine du site. Dans notre cas, pour basic-module, on écrira /js-examples/modules/basic-modules.

Ici, nous avons écrit le chemin d'une façon légèrement différente : on utilise le point (.) afin d'indiquer « l'emplacement courant », suivi du chemin vers le fichier. Cela permet d'éviter d'avoir à écrire l'intégralité du chemin à chaque fois, c'est aussi plus court et cela permet de déplacer le script et le modules sans avoir à modifier les scripts.

Ainsi :

/js-examples/modules/basic-modules/modules/square.js

devient :

./modules/square.js

Vous pouvez voir ces lignes dans main.js.

Note : Pour certains systèmes de module, on peut omettre l'extension de fichier et le point (c'est-à-dire qu'on peut écrire  '/modules/square'). Cela ne fonctionne pas pour les modules JavaScript !

Une fois les fonctionnalités importées dans le script, vous pouvez utiliser les valeurs dans votre script. Dans main.js, après les lignes d'import, on trouvera :

let myCanvas = create('myCanvas', document.body, 480, 320);
let reportList = createReportList(myCanvas.id);

let square1 = draw(myCanvas.ctx, 50, 50, 100, 'blue');
reportArea(square1.length, reportList);
reportPerimeter(square1.length, reportList);

Charger le module via le document HTML

Il faut ensuite pouvoir charger le script main.js sur la page HTML. Pour cela, nous allons voir qu'il y a quelques différences avec le chargement d'un script « classique ».

Tout d'abord, il est nécessaire d'indiquer type="module" dans l'élément <script> afin d'indiquer qu'on charge des modules :

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

Le script qu'on importe ici agit comme le module de plus haut niveau. Si on oublie ce type, Firefox déclenchera une erreur "SyntaxError: import declarations may only appear at top level of a module".

Les instructions import et export ne peuvent être utilisées qu'à l'intérieur de modules et pas à l'intérieur de scripts « classiques ».

Note : Il est aussi possible d'importer des modules dans des scripts qui sont déclarés en incise si on indique bien type="module". On pourra donc écrire <script type="module"> //code du script utilisant les modules ici </script>.

Différences entre les modules et les scripts « classiques »

  • Attention aux tests sur un environnement local : si vous chargez le fichier HTML directement depuis le système de fichier dans le navigateur (en double-cliquant dessus par exemple, ce qui donnera une URL file://), vous rencontrerez des erreurs CORS pour des raisons de sécurité. Il faut donc un serveur local afin de pouvoir tester.
  • On pourra avoir un comportement différent entre un même script utilisé comme un module et un script utilisé de façon « classique ». En effet, les modules utilisent automatiquement le mode strict.
  • Il n'est pas nécessaire d'utiliser l'attribut defer (voir les attributs de <script>) lors du chargement d'un module, ceux-ci sont automatiquement chargés à la demande.
  • Enfin, les fonctionnalités importées ne sont disponibles qu'au sein de la portée du script qui les utilise ! Les valeurs importées ne sont manipulabes que depuis le script, elles ne sont pas rattachées à la portée globale. On ne pourra par exemple pas y accéder depuis la console JavaScript. Bien que les erreurs soient toujours indiquées dans les outils de développement, certaines techniques de débogage ne seront pas disponibles.

Exports par défaut et exports nommés

Jusqu'à présent, nous avons utilisé des exports nommés — chaque valeur est exportée avec un nom et c'est ce nom qui est également utilisé lorsqu'on réalise l'import.

Il existe également un export par défaut — conçu pour simplifier l'export d'une fonction par module et pour faciliter l'interopérabilité avec les systèmes de module CommonJS et AMD (pour plus d'informations, voir ES6 en détails : les modules).

Prenons un exemple pour comprendre le fonctionnement des exports par défaut. Dans square.js, on a une fonction intitulée randomSquare() qui crée un carré avec une taille/couleur/position aléatoires. On souhaite exporter cette fonction par défaut et on écrit donc ceci à la fin du fichier :

export default randomSquare;

On notera ici l'absence d'accolades.

On aurait également pu ajouter export default devant le mot-clé function et la définir comme fonction anonyme :

export default function(ctx) {
  ...
}

Dans le fichier main.js, on importe la fonction par défaut avec cette ligne

import randomSquare from './modules/square.js';

On voit ici aussi l'absence d'accolade car il n'y a qu'un seul export par défaut possible par module (et ici, on sait qu'il s'agit de randomSquare). La ligne ci-avant est en fait une notation raccourcie équivalente à :

import {default as randomSquare} from './modules/square.js';

Note : Pour en savoir plus sur le renommage des objets exportés, voir ci-après Renommage des imports et des exports.

Gestion des conflits de nommage

Jusqu'à présent, notre exemple fonctionne. Mais que se passerait-il si nous ajoutions un module permettant de dessiner une autre forme comme un cercle ou un triangle ? Ces formes disposeraient sans doute également de fonctions telles que draw(), reportArea(), etc. Si on essaie d'importer ces fonctions avec les mêmes noms dans le module de plus haut niveau, nous allons avoir des conflits et des erreurs.

Heureusement, il existe différentes façons de résoudre ce problème.

Renommage des imports et des exports

Entre les accolades utilisées pour les instructions import et export, on peut utiliser le mot-clé as avec un autre nom afin de modifier le nom par lequel on souhaite identifier la fonctionnalité.

Ainsi, les deux fragments qui suivent permettraient d'obtenir le même résultat de façons différentes :

// dans module.js
export {
  fonction1 as nouveauNomDeFonction,
  fonction2 as autreNouveauNomDeFonction
};

// dans main.js
import { nouveauNomDeFonction, autreNouveauNomDeFonction } from './modules/module.js';
// dans module.js
export { fonction1, fonction2 };

// dans main.js
import { fonction1 as nouveauNomDeFonction,
         fonction2 as autreNouveauNomDeFonction } from './modules/module.js';

Prenons un exemple concret. Dans le répertoire renaming, vous verrez le même système de modules que précédemment auquel nous avons ajouté circle.js et triangle.js afin de dessiner et d'écrire des informations sur des cercles et des triangles.

Dans chaque module, on exporte les fonctionnalités avec des noms identiques : l'instruction  export utilisée est la même à chaque fin de fichier :

export { name, draw, reportArea, reportPerimeter };

Lorsqu'on importe les valeurs dans main.js, si on essaie d'utiliser

import { name, draw, reportArea, reportPerimeter } from './modules/square.js';
import { name, draw, reportArea, reportPerimeter } from './modules/circle.js';
import { name, draw, reportArea, reportPerimeter } from './modules/triangle.js';

Le navigateur déclenchera une erreur telle que "SyntaxError: redeclaration of import name" (Firefox).

Pour éviter ce problème, on renomme les imports afin qu'ils soient uniques :

import { name as squareName,
         draw as drawSquare,
         reportArea as reportSquareArea,
         reportPerimeter as reportSquarePerimeter } from './modules/square.js';

import { name as circleName,
         draw as drawCircle,
         reportArea as reportCircleArea,
         reportPerimeter as reportCirclePerimeter } from './modules/circle.js';

import { name as triangleName,
        draw as drawTriangle,
        reportArea as reportTriangleArea,
        reportPerimeter as reportTrianglePerimeter } from './modules/triangle.js';

On aurait pu également résoudre le problème dans les fichiers de chaque module.

// dans square.js
export { name as squareName,
         draw as drawSquare,
         reportArea as reportSquareArea,
         reportPerimeter as reportSquarePerimeter };
// dans main.js
import { squareName, drawSquare, reportSquareArea, reportSquarePerimeter } from './modules/square.js';

Les deux approches fonctionnent. C'est à vous de choisir le style. Toutefois, il est souvent plus pratique d'effectuer le renommage à l'improt, notamment lorsqu'on importe des fonctionnalités de modules tiers sur lesquels on n'a pas le contrôle.

Créer un objet module

La méthode précédente fonctionne mais reste « brouillonne ». Pour faire mieux, on peut importer l'ensemble des fonctionnalités de chaque module dans un objet, de la façon suivante :

import * as Module from './modules/module.js';

Cela récupère tous les exports disponibles depuis module.js et les transforme en propriétés et méthodes rattachées à l'objet Module qui fournit alors un espace de noms (namespace) :

Module.function1()
Module.function2()
etc.

Là encore, prenons un exemple concret avec le répertoire module-objects. Il s'agit du même exemple que précédemment mais qui a été réécrit afin de tirer parti de cette syntaxe. Dans les modules, les exports sont tous écrits ainsi :

export { name, draw, reportArea, reportPerimeter };

En revanche, pour les imports, on les récupère ainsi :

import * as Canvas from './modules/canvas.js';

import * as Square from './modules/square.js';
import * as Circle from './modules/circle.js';
import * as Triangle from './modules/triangle.js';

Dans chaque cas, on peut accéder aux imports comme propriétés des objets ainsi créés :

let square1 = Square.draw(myCanvas.ctx, 50, 50, 100, 'blue');
Square.reportArea(square1.length, reportList);
Square.reportPerimeter(square1.length, reportList);

On obtient alors un code plus lisible.

Classes et modules

Comme mentionné avant, il est possible d'importer et d'exporter des classes. Cette méthode peut aussi être utilisée afin d'éviter les conflits de nommage. Elle s'avère notamment utile lorsque vous utilisez déjà des classes pour construire vos objets (cela permet de garder une certaine cohérence dans le style).

Pour voir le résultat obtenu, vous pouvez consulter le répertoire classes du dépôt où l'ensemble a été réécrit pour tirer parti des classes ECMAScript. Ainsi, square.js contient désormais l'ensemble des fonctionnalités via une classe :

class Square {
  constructor(ctx, listId, length, x, y, color) {
    ...
  }

  draw() {
    ...
  }

  ...
}

Il suffit d'exporter cette classe :

export { Square };

Puis de l'importer ainsi dans main.js :

import { Square } from './modules/square.js';

Ensuite, on peut utiliser cette classe afin de dessiner le carré :

let square1 = new Square(myCanvas.ctx, myCanvas.listId, 50, 50, 100, 'blue');
square1.draw();
square1.reportArea();
square1.reportPerimeter();

Agréger des modules

Il arrivera qu'on veuille agréger des modules entre eux. On peut avoir plusieurs niveaux de dépendances et vouloir simplifier les choses en combinant différents sous-modules en un seul module parent. Pour cela, on pourra utiliser la notation raccourcie suivante :

export * from 'x.js'
export { name } from 'x.js'

Pour voir cela en pratique, vous pouvez consulter le répertoire module-aggregation. Dans cet exemple (construit sur le précédent qui utilise les classes), on a un module supplémentaire intitulé shapes.js qui agrège les fonctionnalités fournies par circle.js, square.js et triangle.js. Les sous-modules ont également été déplacés dans un répertoire shapes situé dans un répertoire modules. L'arborescence utilisée est donc :

modules/
  canvas.js
  shapes.js
  shapes/
    circle.js
    square.js
    triangle.js

Dans chaque sous-module, l'export aura la même forme :

export { Square };

Pour l'agrégation au sein de shapes.js, on écrit les lignes suivantes :

export { Square } from './shapes/square.js';
export { Triangle } from './shapes/triangle.js';
export { Circle } from './shapes/circle.js';

On récupère ainsi l'ensemble des exports de chaque module et on les rend disponibles via shapes.js.

Note : Cette notation ne permet que de rediriger les exports via le fichier. Les objets importés/exportés n'existent pas vraiment dans shapes.js et on ne peut donc pas écrire de code utile qui les manipule.

Dans le fichier main.js, on pourra alors remplacer :

import { Square } from './modules/square.js';
import { Circle } from './modules/circle.js';
import { Triangle } from './modules/triangle.js';

par :

import { Square, Circle, Triangle } from './modules/shapes.js';

Chargement dynamique de modules

Cette nouvelle fonctionnalité permet aux navigateurs de charger les modules lorsqu'ils sont nécessaires plutôt que de tout précharger en avance de phase. Cette méthode offre de nombreux avantages quant aux performances. Voyons comment cela fonctionne.

Pour utiliser cette fonctionnalité, on pourra utiliser import() comme une fonction et lui passer le chemin du module en argument. Cette fonction renverra une promesse, qui sera résolue en un module objet donnant accès aux exports.

import('./modules/monModule.js')
  .then((module) => {
    // Faire qqc avec le module.
  });

Dans nos exemples, regardons le répertoire dynamic-module-imports, également basé sur les classes. Cette fois, on ne dessine rien au chargement de l'exemple mais on ajoute trois boutons — "Circle", "Square" et "Triangle" — qui, lorsqu'ils seront utilisés, chargeront dynamiquement les modules nécessaires et les utiliseront pour charger la forme associée.

Dans cet exemple, nous avons uniquement modifié index.html et main.js — les exports restent les mêmes.

Dans main.js, on récupère une référence à chaque bouton en utilisant document.querySelector(). Par exemple :

let squareBtn = document.querySelector('.square');

Ensuite, on attache un gestionnaire d'évènement à chaque bouton afin qu'on puisse appuyer dessus. Le module correspondant est alors chargé dynamiquement et utilisé pour dessiner la forme :

squareBtn.addEventListener('click', () => {
  import('./modules/square.js').then((Module) => {
    let square1 = new Module.Square(myCanvas.ctx, myCanvas.listId, 50, 50, 100, 'blue');
    square1.draw();
    square1.reportArea();
    square1.reportPerimeter();
  })
});

On voit ici que, parce que la promesse renvoie un objet module à la résolution, la classe est une propriété de cet objet et qu'il faut ajouter cet espace de nom devant le constructeur exporté pour l'utiliser. Autrement dit, avec cette méthode, on doit ajouter Module. devant Square (plutôt que d'utiliser uniquement Square).

Voir aussi