Get started with npm

The ArcGIS Maps SDK for JavaScript's @arcgis/map-components and @arcgis/core packages can be installed locally using the npm command-line interface.

To get started, install both npm and Node.js. Additionally, a client-side build tool that includes a module bundler and a local web server, such as Vite.js, is required for developing and testing your application.

Using a framework or transpiler is optional and depends on your specific requirements. It's important 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 working with local build tools, it's important to understand how the package.json works with dependencies, devDependencies and peerDependencies.

Components

Install

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

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

Create layout

In your index.html file, add the arcgis-map component and reference the main.js file. Each component is a custom element that you add to your application using an HTML tag. They work just like any other HTML element such as a <div></div>.

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

Configure CSS

Configure the CSS and import it in the main.js file. Specific examples are available for a variety of frameworks and module bundlers in the jsapi-resources GitHub repository. Here's a Vite example for the arcgis-map component:

index.css
Use dark colors for code blocksCopy
@import 'https://js.arcgis.com/4.31/@arcgis/core/assets/esri/themes/dark/main.css';

html,
body {
  margin: 0;
}

arcgis-map {
  display: block;
  height: 100vh;
}

main.js
Use dark colors for code blocksCopy
import "./index.css";

Import components

Finally, individually import the SDK's components that you need, such as arcgis-map and arcgis-legend from the @arcgis/map-components package.

This registers the component with the browser's CustomElementRegistry. When the browser encounters the custom element's HTML tag, such as <arcgis-map></arcgis-map>, it creates an instance of the element, adds it to the DOM and enables its functionality.

main.js
Use dark colors for code blocksCopy
import "./index.css";

import "@arcgis/map-components/dist/components/arcgis-map";
import "@arcgis/map-components/dist/components/arcgis-legend";

You can now:

Set properties
Listen for events
Add custom JavaScript logic
Add other components, such as Charts (beta)
Lastly, build the application

In the code snippet below, get a reference to the arcgis-map component using document.querySelector() so that you can add functionality. Then add an event listener for the arcgis-map component's arcgisViewReadyChange event.

main.js
Use dark colors for code blocksCopy
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.
  });

See the tutorial for step-by-step instructions on how to use a View with components.

Loading all components

There is also a convenience pattern that registers all the components once, so you don't have to import them individually for use in your application at runtime. This is useful for prototyping and testing.

Use defineCustomElements() to register a component package in the application. You can immediately start using any component from that package without needing to individually import it. Set the location (local or CDN) of the package's assets via 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.31/assets",
});

Core API

Install

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

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

Create layout

Add a div to your HTML and assign it an id. This is where the map will be injected:

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

Configure CSS

Configure the CSS and import it in the main.js file. Set the height, width, margin and padding properties. Specific examples are available for a variety of frameworks and module bundlers in the jsapi-resources GitHub repository. Here's a Vite example using @arcgis/core:

index.css
Use dark colors for code blocksCopy
#viewDiv {
  padding: 0;
  margin: 0;
  height: 100%;
  width: 100%;
}

main.js
Use dark colors for code blocksCopy
import "./index.css";

Import modules

Finally, individually import the SDK's modules that you need, such as @arcgis/core/Map from the @arcgis/core package.

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.

Import CSS

Choose a light or dark theme for the core API and / or component package and then include the corresponding CSS files in your application. The best practice is to use the ArcGIS CDN where the style files are delivered from an optimized cloud cache that provides efficient loading and improved performance. Including Calcite is optional when only using the API:

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

The SDK uses Calcite in the components and widgets. You can add your own custom functionality using the Calcite Design System, which includes a UI kit, icons, color schemes, and a web component library with UI elements such as buttons, panels and more.

Using local copies of the stylesheets instead of the ArcGIS CDN is optional, and will not benefit from the performance advantages of the 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

The SDK's assets include styles, images, web workers, wasm and localization files.

Default assets

For most use cases when doing local builds, it is recommended to use the SDK's assets from the ArcGIS CDN. They are loaded by default from the following URLs, and no additional configuration is required:

@arcgis/core: https://js.arcgis.com/4.31/@arcgis/core/assets/
@arcgis/map-components: https://js.arcgis.com/map-components/4.31/assets
@esri/calcite-components: https://js.arcgis.com/calcite-components/2.13.2/assets

Using the ArcGIS CDN eliminates the need to bundle these assets with your local build. This reduces the on-disk build size, and can improve build times.

Local assets

There are scenarios where the assets need to be managed locally, such as when working in an environment with no access to the public internet. In these cases, you need to copy the assets into your project from the following directories:

@arcgis/core: /node_modules/@arcgis/core/assets
@arcgis/map-components: /node_modules/@arcgis/map-components/dist/arcgis-map-components/assets/
@esri/calcite-components: /node_modules/@esri/calcite-components/dist/calcite/assets/

A simple way to accomplish this is to configure an npm script that runs during your build process. Here is a Vite example that copies the assets to the correct project folder using cpx2. Follow the cpx2 documentation for installing the package. Then add the copy commands to your package.json scripts for components, the Core API and Calcite. 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
{
  "scripts": {
    "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",
    "copy:calcite": "cpx ./node_modules/@esri/calcite-components/dist/calcite/assets/**/*.* ./public/assets"
  }
}

After copying, the next step is to configure the asset paths in your code to ensure the SDK can correctly locate and load these resources. This step is crucial in a local build environment, because the default asset paths may not align with your project's structure.

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

For more information on working with Calcite components and local assets, refer to Calcite's Get started and the SDK in a disconnected environment guide topic.

Using ESM import statements

ES module import statements are used to load individual API modules. There are three forms of import declarations: default, namespace and named:

Use dark colors for code blocksCopy
// 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 Core API Reference page is guidance on which import syntax to use: default or namespace. Most 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
// Named import
import { load, project } from "@arcgis/core/geometry/projection.js";

You can also use an alias if you think there could be a variable naming conflict; for example, several classes use the load() method:

Use dark colors for code blocksCopy
// 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 esbuild, rollup.js and Webpack 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.

Using the ESM CDN

The ES modules CDN is for testing and prototyping 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:

Use dark colors for code blocksCopy
<link rel="stylesheet" href="https://js.arcgis.com/4.31/@arcgis/core/assets/esri/themes/light/main.css">

<script type="module">
  import Map from 'https://js.arcgis.com/4.31/@arcgis/core/Map.js';
  const map = new Map({
    basemap: "topo-vector"
  });
</script>

Additional information

Please refer to these additional links for further information: