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 local 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
3
4
5
// Default import
import WebMap from "@arcgis/core/WebMap";

// Namespace import
import * as projection from "@arcgis/core/geometry/projection";

At the top of each module's API Reference page is guidance on which import syntax to use: default or namespace. Most of the modules use a default import syntax as shown in the import WebMap Class example above. Other modules, such as those providing helper functions, use a namespace import similar to the import * as projection example. Depending on your stylistic preference, instead of a namespace import you can also use a named import to reference the exact method that you need:

  
1
2
// Named import
import { load, project } from "@arcgis/core/geometry/projection";

And, you can also use an alias if you think there could be a variable naming conflict, for example a number of classes use the load() method:

  
1
2
// Named import using an alias
import { load as projectionLoad, project } from "@arcgis/core/geometry/projection";

Whether you use namespace or named imports, module bundlers such as Webpack and rollup.js will treat them the same when it comes to treeshaking, which is the process of removing unused code in order to create the smallest, most efficient build.

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.21/@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 with @arcgis/core 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 snippet refactored with @arcgis/core ES module paths:

  
1
2
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.