Get started with npm

The ArcGIS Maps SDK for JavaScript's @arcgis/map-components and @arcgis/core packages are available for local installation from npm.

In addition to using npm, depending on your project, you may need additional modern build tools, including a framework, module bundler, transpiler, node.js and more. You are expected to have a basic understanding of how these tools work. For an introduction to these concepts, see the Additional Information section below.

Managing dependencies

When using npm, the package.json file specifies the initial set of packages needed to run and build the application. When each of these npm packages are installed, they also specify their own unique dependencies.

If you are new to client-side web development tools, it's important to understand how the package.json works with dependencies, devDependencies and peerDependencies.

Components

To use map components, install the @arcgis/map-components package into your project:

Use dark colors for code blocksCopy
npm install @arcgis/map-components

In your index.html file, add the arcgis-map component and reference the main.js file:

index.html
Use dark colors for code blocksCopy
<body>
   <arcgis-map item-id="e691172598f04ea8881cd2a4adaa45ba"></arcgis-map>
   <script type="module" src="/main.js"></script>
</body>

Then, in the main.js file, configure the CSS and import the @arcgis/map-components package:

main.js
Use dark colors for code blocksCopy
import "./index.css";
import { defineCustomElements as defineMapElements } from "@arcgis/map-components/dist/loader";

defineMapElements(window, {
  resourcesUrl: "https://js.arcgis.com/map-components/4.30/assets",
});

You can now:

Register components
Set properties
Listen for events
Add custom JavaScript logic using the core JavaScript API library (see the tutorial for step-by-step instructions)

In the code snippet below, get a reference to the arcgis-map component so that you can add functionality:

main.js
Use dark colors for code blocksCopy
/**
 * Use `document.querySelector()` to get a reference to the `arcgis-map` component.
 * Add an event listener for the `arcgis-map` component's `viewReadyChange` event.
 */
document
  .querySelector("arcgis-map")
  .addEventListener("arcgisViewReadyChange", (event) => {
    /**
     * Get a reference to the `WebMap`
     * from the `event.detail` object.
     */
    const { map } = event.detail;
    // Add more functionality here.
  });

Registering components

Registering components is the process of making them available for use in an application. This can either be done via loading all components at once or individually loading each component.

Loading all components

When loading all components, components are loaded and registered once, making them all available for use in your application at runtime. The defineCustomElements function is used to register components in the browser. You only need to call this function once for each component package you wish to use. Each component package must specify the location of its (local or CDN) assets. This can be done by setting the resourcesUrl option. Setting the asset path for one component package will not affect the asset path for other component packages. Using the ArcGIS CDN hosted assets is recommended for best performance and reducing the build size of your application.

Use dark colors for code blocksCopy
import { defineCustomElements as defineMapElements } from "@arcgis/map-components/dist/loader";

// Point to ArcGIS CDN hosted assets
defineMapElements(window, {
  resourcesUrl: "https://js.arcgis.com/map-components/4.30/assets",
});

Individually loading components

In this approach, you manually load and initialize each component before using them. The assets are loaded from the ArcGIS CDN by default from: "https://js.arcgis.com/map-components/4.30/assets".

Use dark colors for code blocksCopy
/**
 * Uncomment when working with local assets for your component package
 */

// import { setArcgisAssetPath as setMapAssetPath} from '@arcgis/map-components/dist/components';
// setMapAssetPath(`${location.origin}${location.pathname}assets`);

/*
 * Individually import each component you wish to use
 */
import "@arcgis/map-components/dist/components/arcgis-map";

API

To use the API's ES modules, install the @arcgis/core package into your project:

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

Add a div to your HTML and assign it an id:

index.html
Use dark colors for code blocksCopy
<div id="viewDiv"></div>

Next, configure the CSS and use import statements to load individual modules. Then initialize the map and start adding custom functionality:

main.js
Use dark colors for code blocksCopy
import "./index.css";
import Map from "@arcgis/core/Map";
import MapView from "@arcgis/core/views/MapView";

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

const view = new MapView({
  container: "viewDiv", // reference the div id
  map: map,
  zoom: 4,
  center: [15, 65]
});

More information is available in the Using ESM import statements guide topic.

Configure CSS

Choose a light or dark theme for the map components package and then include the corresponding CSS files in your application. The best practice is to use the ArcGIS CDN, and including Calcite is optional when only using the API:

index.css
Use dark colors for code blocksCopy
@import "https://js.arcgis.com/4.30/@arcgis/core/assets/esri/themes/dark/main.css";
@import "https://js.arcgis.com/calcite-components/2.9.0/calcite.css";

Using local copies of the stylesheets is optional. However, this approach will not benefit from the advantages of using the ArcGIS CDN:

index.css
Use dark colors for code blocksCopy
@import "@arcgis/core/assets/esri/themes/dark/main.css";
@import "@esri/calcite-components/dist/calcite/calcite.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.

Working with assets

For most use cases, whether you are using components or the ES modules, it is recommended to use the SDK's assets from the ArcGIS CDN. The assets include styles, images, web workers, wasm and localization files. One advantage of using the CDN is the CSS styles will not need to be bundled on-disk with your local build, and the files are downloaded from an optimized cloud cache.

If you need to manage the SDK's assets locally, copy them into your project from /node_modules/@arcgis/ + packageName/assetPath, and then set the asset path to ensure the assets are resolved correctly. A simple way to accomplish this is to configure a npm script that runs during your build process. For example, on a Mac or Windows terminal you could use cpx2.

Here’s a Vite example to copy the 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
{
  "script": {
    "dev": "npm run copy:all && vite",
    "build": "npm run copy:all && vite build",
    "copy:all": "npm run copy:components && npm run copy:core",
    "copy:components": "cpx ./node_modules/@arcgis/map-components/dist/arcgis-map-components/assets/ ./public/assets",
    "copy:core": "cpx ./node_modules/@arcgis/core/assets ./public/assets"
  }
}

index.js
Use dark colors for code blocksCopy
// Configure the asset path to your desired directory for components and core
import { setArcgisAssetPath as setMapAssetPath} from '@arcgis/map-components/dist/components';
import esriConfig from "@arcgis/core/config.js";

setMapAssetPath("./public/assets");
esriConfig.assetsPath = "./public/assets";

AMD local build (deprecated)

The are only a few reasons for building locally with AMD. These capabilities were deprecated at 4.29 will be retired at 4.31:

Working with AMD TypeScript definitions via the deprecated arcgis-js-api package.
Using the deprecated esri-loader library to inject the AMD modules at runtime.
Using legacy Dojo 1 or RequireJS.

Additional information

Please refer to these additional links for further information: