Introduction to tooling


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. Starting at 4.18, the API is also available as ES modules. 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 CDN (AMD) 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, and the AMD and ES modules have the same API capabilities.

If you are using 4.18+ with a framework or build tools, and you aren't using Dojo 1 or RequireJS, then you should be building with ES modules.

Compare AMD and ES modules

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

CDN (AMD)ESM local buildAMD local build
No installation, configuration or local build requiredX
Fast download performance via CDN cacheX
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


The advantages of using the CDN include:

  • Fast download and highly optimized caching for the API modules.
  • No installation or configuration.
  • Easy to update applications to the next API version.

ES modules local build

The advantages of building ES modules locally include:

  • Standardized module system adopted by modern build tools.
  • 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, geometry engine.

The disadvantages include:

  • Updates require installing a new version.

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.