Build with ES modules

Introduction

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

Prerequisites

Depending on your project 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.

The JavaScript Maps SDK also has System Requirements.

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:

Use dark colors for code blocksCopy
1
npm install @arcgis/core

Then, use import statements to load individual modules. There are three forms of import declarations: default, namespace and named:

Use dark colors for code blocksCopy
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:

Use dark colors for code blocksCopy
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:

Use dark colors for code blocksCopy
1
2
// Named import using an alias
import { load as projectionLoad, project } from "@arcgis/core/geometry/projection.js";

Whether you use default, 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

Use dark colors for code blocksCopy
1
@import "https://js.arcgis.com/4.29/@arcgis/core/assets/esri/themes/dark/main.css";

The pattern for specifying this @import url path is dependent on your framework or module bundler. MDN provides more information on the various patterns for using @import. And, 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, web workers, wasm 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, on a Mac terminal or on Windows you could use cpx2.

Here’s a React example to copy local assets. Check your framework or bundler documentation for best practices on using npm scripts or plugins for copying files:

package.json

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
{
  "script": {
    "start": "npm run copy && react-scripts start",
    "build": "npm run copy && react-scripts build",
    "copy": "cpx ./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.

Use dark colors for code blocksCopy
1
2
import esriConfig from "@arcgis/core/config.js";
esriConfig.assetsPath = "./assets";

index.css

In the CSS file, be sure to reference the local copy of the CSS. The pattern for specifying this @import url path is dependent on your framework or module bundler. MDN provides more information on the various patterns for using @import.

Use dark colors for code blocksCopy
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 code snippet:

index.html

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

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

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

Additional information

Please refer to these additional links for further information:

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