ArcGIS API for JavaScript - Working with frameworks and build tools just got easier

Do you use the ArcGIS API for JavaScript with a 3^rd party framework and/or create local builds?

The December release of the JavaScript API (version 4.18) will include an option for consuming the API as ES modules (Beta). This will make the process of integrating the JavaScript API with any framework and build tooling much easier.

If you aren’t already familiar with ES modules, they are also known as ECMAScript Modules, or simply ESM. They are an official, standardized module system for working with modern JS that has been adopted by all the major browsers.

How do I get started?

Install the new ES modules package (@arcgis/core) using NPM:

npm install @arcgis/core

Then use import statements to load individual modules into your application. Note, the ES modules package naming convention uses /core which is different from the /esri used by the AMD CDN modules.

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

const webmap = new WebMap({
  portalItem: {
    id: '05e015c5f0314db9a487a9b46cb37eca',
  },
});

const view = new MapView({
  container,
  map: webmap
});

The second step is to copy the API’s assets; which includes styles, images, fonts, and localization files, from the @arcgis/core/assets folder to your build folder. There are various ways to accomplish this depending on your build tooling, but a simple way is to configure an NPM script that runs during your build process. For example, you could npm install ncp and configure a script in package.json to copy the folder. Here’s a React example of this:

{
    "script": {
        "start": "npm run copy && react-scripts start",
        "build": "npm run copy && react-scripts build",
        "copy": "ncp ./node_modules/@arcgis/core/assets ./public/assets"
    }
}

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';

That’s all you have to do to bring the API into your application. Now you can run your build and the API’s ES modules will be bundled along with all your other imports.

Should I migrate to the new modules?

If you are currently using the AMD CDN modules without a JS framework or creating local builds, then there’s no need to plan on migrating. You can continue using the AMD modules as you have been doing.

If you are using a framework with esri-loader, arcgis-webpack-plugin or a custom build of the API , then consider migrating. The benefits of this approach includes:

• Simplified code
• Native support in the browser
• Minimal configuration
• Seamless integration with all modern frameworks and build tools.

Early Access

The ES modules project is still in development. It is not intended for use in production applications, and is not covered by technical support. After the beta release in December, we have a production release planned for early 2021.

We invite you to try out the new modules while they are in development and provide your feedback. Please visit the /next repo for more information and to submit your feedback. Also, there are samples available that demonstrate the basic concepts of using the modules with a variety of JS frameworks and module bundlers.