How Was the API Consumed Before ES Modules Were Available?
The API has always been available as Asynchronous Module Definition (AMD) modules, and it continues to be available as AMD modules for developers who prefer this format. If your app references Esri’s content delivery network (CDN) to access the API via https://js.ArcGIS.com/<API version number>, you are using the AMD version.
Understanding AMD and ES Modules
With both AMD and ES modules, API functionality is divided into logical subsets and packaged as modules. AMD modules use a require() method and a third-party script loader to load modules and their dependencies.
ES modules 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. An example showing the differences between the two coding patterns is shown in Listing 1.
Should You Migrate to ES Modules?
If you aren’t integrating with a framework or creating custom builds of the API, there is no need to migrate to the new ES modules. The AMD modules will continue to be available alongside the ES modules for the foreseeable future. Both formats have the same capabilities because they are built from the same code base.
AMD modules are hosted on the CDN and therefore offer these benefits when accessing the API in this manner, as opposed to creating custom builds:
- Fast download and highly optimized caching for API modules
- No installation or configuration required
- It is easy to update applications to the next API version
If you are integrating with a framework or creating local builds, you should consider using ES modules. This will simplify your implementation as ES modules do not require a separate script loader or additional configuration. When using AMD, you typically either use a webpack plugin to integrate the API into your webpack build or use esri-loader with framework tools or other bundlers.
Note that you will still want to use AMD modules when creating local builds if your app uses Dojo1 or RequireJS.
Get Started Using ES Modules
Whether you are creating a new application or integrating the API in an existing application, the first step is to install the API using npm with the following command:
npm install @arcgis/core
Then use import statements to load individual modules. Note that the ES modules package naming convention uses /core rather than /esri, which is used by the AMD CDN modules, as shown in Listing 2.
You will need to copy the API assets (which includes styles, images, fonts, pre-built API web worker JS files, and localization files) from the @arcgis/core/assets folder to your build folder. A simple way to accomplish this is to configure a Node Package Manager (NPM) script that runs during your build process. For example, use npm to install ncp and configure a script in package.json to copy the folder. See the React example in Listing 3.
The final step is to set up the CSS. Choose a theme and then configure your code to copy the theme files from @arcgis/core/assets/esri/themes/ into your project. Listing 4 provides a React example. Now you can run your build and the API’s ES modules will be bundled along with all your other imports.
Refactor Code, If Necessary
Documentation and Examples
Road Map for ES Module Migration
At version 4.18, ES modules were released as beta. The production release is planned for early 2021. If you try the modules while they are in beta and they meet your app’s requirements, you can use them in your app. The modules have been broadly tested but they are still considered provisional as they could change based yon feedback or an improved design.
ES modules are covered by Esri Technical Support while they are in beta so you can obtain support as needed. If you have feedback on the modules, associated documentation, or sample code, you can submit your comments or questions to the early access repository.
If you are using a framework or creating custom builds, use ES modules to make your development work easier. If you are not using a framework or creating custom builds, you don’t need to do anything.