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:
Then use import
statements to load individual modules:
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 Web
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:
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:
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
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.assets
.
Managing assets locally
If you need to manage the API's assets locally, copy them into your project from /node_
, and then set config.assets
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
App.js
The path used in the assets
property will vary depending on where the assets are placed within your project.
index.css
The pattern for specifying this @import
path is dependent on your framework or module bundler.
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
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:
This is the snippet refactored with @arcgis/core
ES module imports:
@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:
This is the snippet refactored with @arcgis/core
ES module paths:
Additional information
Please refer to these additional links for further information: