Introduction to tooling

Overview

The ArcGIS Maps SDK for JavaScript is available as AMD and ES modules. Since version 4.0 the API has been shipped as AMD, for example the CDN uses AMD modules. ES modules became available at version 4.18. Your implementation use case will affect which modules to use with your application, framework or build tools.

The API's modules divide the functionality into logical subsets. The AMD modules implement the Asynchronous Module Definition format, and they use a require() method and a third-party script loader to load modules and their dependencies. ES modules, also known as ECMAScript Modules or simply ESM, are an official, standardized module system that works natively with all modern browsers through import statements. ES modules do not require a separate script loader.

Should I migrate to ES modules?

If you use the AMD CDN without a JavaScript framework or local build tools, then there’s no need to migrate. The AMD modules will be available for the foreseeable future.

ES modules and AMD modules implement the same API functionality. For example, the following code snippets provide equivalent capabilities.

ES module

1
2
3
4
5
6
7
8
9
10
11
import Map from '@arcgis/core/Map.js';
import MapView from '@arcgis/core/views/MapView.js';

const map = new Map({
  basemap: "topo-vector"
});

const view = new MapView({
  container: "viewDiv",
  map: map
});

AMD

1
2
3
4
5
6
7
8
9
10
require(["esri/Map", "esri/views/MapView"], (Map, MapView) => {
  const map = new Map({
    basemap: "topo-vector"
  });

  const view = new MapView({
    container: "viewDiv",
    map: map
  });
});

Compare AMD and ES modules

Here are some common reasons for using AMD and ES modules.

CDN (AMD)

The advantages of using the AMD CDN include:

• Fast download and highly optimized caching.
• No installation or configuration.
• API automatically updates to the latest version.

CDN (ESM)

The ES modules CDN is for testing only, it is not optimized for module loading performance. For best performance with ES modules, build them locally.

ES modules local build

The advantages of building ES modules locally include:

• Standardized module system that natively integrates with major browsers.
• Does not require separate helper or module loader libraries.
• Seamless integration with most modern frameworks and build tools.
• No multiple define issues when working with certain 3rd party libraries.
• Provides server-side capabilities for node.js deployments, for example, geometryEngine.

The disadvantages include:

• API updates require installing a new version and rebuilding your application.

AMD local build

The are only a few reasons for building locally with AMD:

• When using version 4.17 or earlier of the API with most frameworks and build tools.
• When working with Dojo 1 or RequireJS.

The disadvantages include:

• Requires helper libraries such as esri-loader and arcgis-webpack-plugin when working with modern frameworks and build tools.
• Modules loaded with esri-loader are not bundled and optimized with the build, they are requested from the CDN at runtime.
• The arcgis-webpack-plugin has special configuration options and it may require additional libraries to extend webpack.