Build with ES modules

Introduction

ES modules are an official, standardized module system for working with modern JS that has been adopted by all the major browsers. The ArcGIS API for JavaScript's ES modules are available for installation from npm via @arcgis/core.

For examples using the ES modules with frameworks and build tools, visit the jsapi-resources GitHub repository.

Get started

Install the modules into your project:

 
1
npm install @arcgis/core

Then use import statements to load individual modules.

  
1
2
import WebMap from "@arcgis/core/WebMap";
import MapView from "@arcgis/core/views/MapView";

Configure CSS

Choose a theme and then configure your code to use the ArcGIS CDN, for example:

index.css

 
1
@import "https://js.arcgis.com/4.19/@arcgis/core/assets/esri/themes/dark/main.css";

Or, if you are working with local assets see the Managing assets locally section.

Working with assets

For most local builds, the API's assets are pulled from the ArcGIS CDN at runtime and there is no need for additional configuration. The assets include styles, images, fonts and localization files. This behavior is based on the default setting for config.assetsPath.

Managing assets locally

If you need to manage the assets locally, copy them into your project from /node_modules/@arcgis/core/assets, and then set config.assetsPath to insure the asset paths are resolved correctly. A simple way to accomplish this is to configure an 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. Here’s a React example:

package.json

       
1
2
3
4
5
6
7
{
  "script": {
    "start": "npm run copy && react-scripts start",
    "build": "npm run copy && react-scripts build",
    "copy": "ncp ./node_modules/@arcgis/core/assets ./public/assets"
  }
}

App.js

  
1
2
import esriConfig from "@arcgis/core/config.js";
esriConfig.assetsPath = "./assets";

index.css

 
1
@import "@arcgis/core/assets/esri/themes/dark/main.css";

Configure web server

The web server hosting configuration where you develop and host the ArcGIS API for JavaScript will need specific MIME/type registration.

Migrate to ES modules

If you already use esri-loader or @arcgis/webpack-plugin then in addition to the steps listed above you will mainly be refactoring to use the new modules, you will not need to completely re-write your code. The majority of code that implements the ArcGIS API for JavaScript functionality will stay the same. Here are some examples to demonstrate the concepts.

esri-loader

To migrate from esri-loader to ES modules, your code will need to be refactored to ES modules.

Here is a snippet of esri-loader code:

      
1
2
3
4
5
6
import { loadModules } from "esri-loader";

const [Map, MapView] = await loadModules([
  "esri/Map",
  "esri/views/MapView"
]);

This is the snippet refactored to ES module imports:

  
1
2
import Map from "@arcgis/core/Map";
import MapView from "@arcgis/core/views/MapView";

@arcgis/webpack-plugin

To migrate from using AMD modules with @arcgis/webpack-plugin to using ES modules. after installing @arcgis/core refactor your imports to use the new path.

Here is an @arcgis/webpack-plugin code snippet with esri-based pathnames:

  
1
2
import Map from "esri/Map";
import MapView from "esri/views/MapView";

This is the code refactored with @arcgis/core module paths:

   
1
2
3
// ES modules
import Map from "@arcgis/core/Map";
import MapView from "@arcgis/core/views/MapView";

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