Using $arcgis.import(): Simplify Module Loading in ArcGIS Maps SDK for JavaScript CDN Apps

The JavaScript module landscape continues to evolve rapidly. While AMD served CDN-based vanilla JavaScript applications well, ES modules are now considered the standard for web-based applications. For example, TypeScript has announced plans to deprecate AMD output in the future, signaling this broader industry trend.

For developers using the ArcGIS Maps SDK for JavaScript via CDN, this shift brings both opportunities and important considerations.

With version 4.32 of the Javascript Maps SDK, we introduced $arcgis.import(), a promise-based API for loading SDK modules in applications built with the CDN. When compared to callback-based AMD approaches, it provides a cleaner syntax for implementing lazy loading patterns like dynamic and conditional module loading. It works seamlessly with modern async/await patterns while maintaining full compatibility with existing AMD-based applications. It is also designed to transparently support ES modules in the future with zero code changes required.

For new CDN-based applications, we recommend using $arcgis.import() for module loading. While require() will continue to be supported, $arcgis.import() is the preferred and future facing approach.

In this post, you’ll learn:

• How $arcgis.import() compares to traditional require() patterns
• When and why you should adopt this approach
• Practical patterns for dynamic and conditional module loading
• How this prepares your codebase for future ES module support

Current Module Loading Patterns

The JavaScript Maps SDK supports three primary consumption patterns:

NPM + Build Tools (ESM)

You can install @arcgis/core via NPM and use standard ES module syntax with bundlers like Vite, Webpack, or Rollup. Modern frameworks like React, Vue, Svelte, and Angular follow this path, which is already fully ESM.

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

CDN with require()

Load the SDK directly from the Esri CDN using the legacy AMD format and the require() function. This continues to be supported but has limitations when it comes to modern JavaScript workflows, especially around code-splitting and dynamic import patterns.

<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>

If you’re developing your application using the AMD modules or an AMD build tool, it is recommended to migrate to using $arcgis.import() or ES modules and modern build tools.  See our guide to get started.

CDN with $arcgis.import

$arcgis.import()is a CDN-hosted only, a promise-based module loader built directly into the SDK. It accepts a single module, or an array of module paths and returns a promise that resolves to the loaded modules.

<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>

Note that it uses the @arcgis/core/ ES modules path format instead of the traditional esri/ AMD paths.

Unlike the traditional AMD-based apps that rely on global require() function, $arcgis.import(), does not need any global imports. It works seamlessly in modern module environments.

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

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

<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>

<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>

<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>