Introduction to tooling

Overview

The ArcGIS API 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.

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

AMD

Use dark colors for code blocksCopy
          
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
  });
});

ES module

Use dark colors for code blocksCopy
           
1
2
3
4
5
6
7
8
9
10
11
import Map from '@arcgis/core/Map';
import MapView from '@arcgis/core/views/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)CDN (ESM)ESM local buildAMD local build
No installation, configuration or local build requiredXX
Fast download performance via CDN cacheX
For testing onlyX
Easy installation via npmX
Seamless integration with most modern frameworks and build toolsX
Using API version 4.17 or earlier with a framework or build toolsX
Using Dojo 1 or RequireJSX

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, for example when using Angular 9+.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.