Build with ES modules

Introduction

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

Prerequisites

Depending on your requirements you may need a variety of modern build tools including a framework, module bundler, transpiler, node.js, npm and more. In order to use the @arcgis/core modules it is expected that you have a basic understanding of how these tools work. For an introduction to these concepts, see the Additional Information section below.

Get started

This section highlights the basic steps for a minimal installation of @arcgis/core into an existing project built with modern tooling.

Begin by installing 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.js";

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

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.js";

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.js";

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.27/@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

By default, the API's assets are pulled from the ArcGIS CDN at runtime and there is no need for additional configuration. One advantage of using the CDN is the APIs CSS styles will not need to be bundled on-disk with your local build. 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 API's assets locally, copy them into your project from /node_modules/@arcgis/core/assets, and then set config.assetsPath to ensure 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

The path used in the assetsPath property will vary depending on where the assets are placed within your project.

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

index.css

The pattern for specifying this @import path is dependent on your framework or module bundler.

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 Maps SDK for JavaScript will need specific MIME/type registration.

Using the ESM CDN

The ES modules CDN is for testing only, it is not optimized for performance. For best performance in a production application, build the @arcgis/core modules locally. A sample is available in the jsapi-resources GitHub repository. Here's an HTML and JavaScript example:

index.html

1
2
3
4
5
6
7
8
9
<link rel="stylesheet" href="https://js.arcgis.com/4.27/@arcgis/core/assets/esri/themes/light/main.css">

<script type="module">
  import Map from 'https://js.arcgis.com/4.27/@arcgis/core/Map.js';

  const map = new Map({
    basemap: "topo-vector"
  });
</script>

Migrate to ES modules

If you already use esri-loader or @arcgis/webpack-plugin with AMD modules, 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 Maps SDK 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.js";
import MapView from "@arcgis/core/views/MapView.js";

@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.js";
import MapView from "esri/views/MapView.js";

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

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

Additional information

Please refer to these additional links for further information:

• ArcGIS Maps SDK for JavaScript - Working with frameworks and build tools just got easier
• MDN - JavaScript modules
• MDN - Client-side tooling overview
• MDN - Introducing a complete toolchain