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. Starting at 4.18, the API is also available as ES modules (beta). 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 build | AMD local build | |
|---|---|---|---|
| No installation, configuration or local build required | X | ||
| Fast download performance via CDN cache | X | ||
| Easy installation via npm | X | ||
| Seamless integration with most modern frameworks and build tools | X | ||
| Using API version 4.17 or earlier with a framework or build tools | X | ||
| Using Dojo 1 or RequireJS | X |
CDN (AMD)
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.
- Works with Dojo 1 and 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 with the build, they are requested from the CDN at runtime.
- The arcgis-webpack-plugin needs to be configured and it may require additional libraries to extend webpack, for example when using Angular 9+.