Simplifiez le chargement des modules dans vos applications CDN avec $arcgis.import()

Le paysage des modules JavaScript évolue rapidement. Historiquement, le format AMD convenait bien aux applications JavaScript  vanilla chargées via un CDN, mais aujourd’hui, les modules ES (ESM) sont devenus la norme pour les applications web modernes. TypeScript, par exemple, a annoncé la dépréciation prochaine de la sortie en AMD, confirmant cette tendance de fond.

Pour les développeurs qui utilisent l'ArcGIS Maps SDK for JavaScript via le CDN, cette transition ouvre de nouvelles perspectives… tout en demandant quelques ajustements.

 

Depuis la version 4.32, le SDK introduit une nouvelle API asynchrone : $arcgis.import(), une API basée sur des promesses pour charger les modules du SDK dans les applications construites avec le CDN.

 

Comparée aux approches AMD reposant sur des fonctions de rappel (require()), elle offre une syntaxe plus claire pour mettre en œuvre des modèles de chargement différé (lazy loading) ou conditionnel (conditional loading). Elle s’intègre naturellement aux modèles modernes utilisant async / await, tout en restant entièrement compatible avec les applications AMD existantes. Elle a également été conçue pour prendre en charge de manière transparente les modules ES à l’avenir, sans nécessiter de modification du code.

 

Pour toute nouvelle application utilisant le SDK via le CDN, il est désormais recommandé d’utiliser $arcgis.import().
require() reste pris en charge, mais $arcgis.import() est la méthode la plus moderne et la plus pérenne.

 

Dans cet article, je vous propose de comparer $arcgis.import() au modèle require() traditionnel, de comprendre quand et pourquoi préférer cette nouvelle approche, de découvrir les modèles pratiques pour le chargement dynamique et d'envisager un plan de migration.

Trois façons de consommer le SDK

NPM + outils de build (ESM)

Vous pouvez installer le SDK via NPM (@arcgis/core) et utiliser la syntaxe ESM avec un bundler comme Vite, Webpack ou Rollup. Les frameworks modernes tels que React, Vue, Svelte et Angular suivent cette approche, qui est déjà entièrement conforme à la norme ESM.

import WebMap from "@arcgis/core/WebMap.js";
import FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";

 

CDN avec require()

L'approche historique, c'est de charger le SDK directement depuis le CDN d’Esri en utilisant le format AMD et la fonction require().
Cette méthode historique reste prise en charge, mais elle présente certaines limites pour les workflows JavaScript modernes, notamment lorsqu’il s’agit de code-splitting ou d’imports dynamiques.

<script src="https://js.arcgis.com/4.33/"></script>
<script>
  require(["esri/WebMap", "esri/layers/FeatureLayer"], function (WebMap, FeatureLayer) {
    const map = new WebMap({ basemap: "topo-vector" });
    const layer = new FeatureLayer({ 
      url: "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/ACS_Housing_Tenure_by_Heating_Fuel_Boundaries/FeatureServer/1" 
    });
  });
</script>

Si vous développez actuellement vos applications avec des modules AMD ou à l’aide d’un outil de build compatible AMD, il est recommandé de migrer vers $arcgis.import() ou vers les modules ES (ESM) et des outils de build modernes.

 

CDN avec $arcgis.import()

$arcgis.import() est un chargeur de modules basé sur des promesses, disponible uniquement pour les applications hébergées via le CDN.
Il est intégré directement au SDK et accepte un module unique ou un tableau de chemins de modules, puis renvoie une promesse qui se résout une fois les modules chargés.

<script type="module">
  const [Map, FeatureLayer] = await $arcgis.import([
    "@arcgis/core/Map.js",
    "@arcgis/core/layers/FeatureLayer.js"
  ]);

  const map = new Map({ basemap: "topo-vector" });
  const layer = new FeatureLayer({ 
    url: "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/ACS_Housing_Tenure_by_Heating_Fuel_Boundaries/FeatureServer/1" 
  });
</script>

 

Remarquez que cette méthode utilise le format de chemin ES modules (@arcgis/core/...) au lieu des chemins AMD traditionnels (esri/...).
Contrairement aux applications AMD classiques qui s’appuient sur la fonction globale require(), $arcgis.import() ne nécessite aucun import global. Il fonctionne de manière transparente dans les environnements modernes basés sur des modules ES.

Exemples d’utilisation

Charger un seul module

<script type="module">
  const Graphic = await $arcgis.import("@arcgis/core/Graphic.js");

  const graphic = new Graphic({ /* ... */ });
</script>

 

Charger plusieurs modules

<script type="module">
  const [Map, Multipoint, FeatureLayer] = await $arcgis.import([
    "@arcgis/core/Map.js",
    "@arcgis/core/geometry/Multipoint.js",
    "@arcgis/core/layers/FeatureLayer.js"
  ]);
</script>

Cas d’usage : lazy loading

$arcgis.import() offre une syntaxe plus claire pour les modèles de chargement dynamique et conditionnel de modules, comparée aux approches AMD basées sur des fonctions de rappel (callbacks). Ce niveau de flexibilité est difficile à atteindre avec les blocs require traditionnels de l’AMD.

Le chargement dynamique de modules permet de ne charger un module que lorsqu’il est nécessaire, ce qui améliore les performances de chargement initial de l’application.
Dans l’exemple ci-dessous, le module FeatureLayer est chargé dynamiquement lorsque l’utilisateur clique sur un bouton : 

<script type="module">
  document.getElementById("loadButton").addEventListener("click", async () => {
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");
    const layer = new FeatureLayer({ url: "https://services.arcgis.com/..." });
    map.add(layer);
  });
</script>

Le chargement conditionnel de modules permet quant à lui de charger différents modules selon les conditions d’exécution.
Par exemple, il est possible de charger des couches différentes en fonction du niveau de zoom de la carte :

<script type="module">
  const Map = await $arcgis.import("@arcgis/core/Map.js");

  view.watch("zoom", async (zoom) => {
    if (zoom > 10) {
      const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");
      // Load city-level layer
    } else {
      const GraphicsLayer = await $arcgis.import("@arcgis/core/layers/GraphicsLayer.js");
      // Load country-level layer
    }
  });
</script>

Migration depuis require()

Si vous utilisez encore le CDN avec require(), c’est le bon moment pour passer à $arcgis.import(). Bonne nouvelle : $arcgis.import() coexiste avec require(), ce qui permet une migration progressive.
Il suffit de :

• remplacer les appels require() par await $arcgis.import() ;
• utiliser la déstructuration de tableau pour récupérer les modules ;
• ajouter type="module" dans les balises <script> ;
• remplacer les callbacks d’erreur par des blocs try/catch.

Prochaines étapes

• Essayez $arcgis.import() dans vos applications utilisant le CDN.
• Utilisez-le pour charger des modules de façon dynamique, en fonction des interactions utilisateur ou des changements d’itinéraire.
• Consultez les exemples qui illustrent ce nouveau modèle.