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 @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:

npm install @arcgis/core

Then use import statements to load individual modules.

import WebMap from '@arcgis/core/WebMap';
import MapView from '@arcgis/core/views/MapView';

Copy assets

You will need to copy the API’s assets, which includes styles, images, fonts, and localization files, from the @arcgis/core/assets folder to your build folder. 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
{
    "script": {
        "start": "npm run copy && react-scripts start",
        "build": "npm run copy && react-scripts build",
        "copy": "ncp ./node_modules/@arcgis/core/assets ./public/assets"
    }
}

Configure CSS

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. Here’s a React example:

 // React - index.js
 import '@arcgis/core/assets/esri/themes/dark/main.css';

Examples

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

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:

import { loadModules } from 'esri-loader';

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

This is the snippet refactored to ES module imports:

import Map from '@arcgis/core/Map';
import MapView from '@arcgis/core/views/MapView';

arcgis-webpack-plugin

To migrate from arcgis-webpack-plugin to ES modules, refactor your imports to use the new folder path.

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

import Map from 'esri/Map';
import MapView from 'esri/views/MapView';

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

// ES modules
import Map from '@arcgis/core/Map';
import MapView from '@arcgis/core/views/MapView';