Introduction to tooling

Overview

The ArcGIS Maps SDK for JavaScript is available as web components, ES modules and AMD modules. Your implementation use case will affect which modules to use with your application, framework or build tools.

The component library wraps the API's modules in a collection of pre-built UI components for building web mapping applications with minimal code. The API's modules divide the functionality into logical subsets. ES modules, also known as ESM, are an official, standardized module system that works natively with browsers through import statements. ES modules do not require a separate script loader. The AMD modules implement the Asynchronous Module Definition format. They use the require() method and a third-party script loader to load modules and their dependencies.

Depending on your requirements, using components or ES modules in combination with frameworks and build tools can offer significant advantages over vanilla JavaScript. A good introduction to these concepts is available in the Client-side tooling overview on MDN.

Compare use cases

Here are some common reasons for choosing the various approaches.

ComponentsESM local buildCDN (ESM)
Reduced boilerplate code (CDN and local builds)X
Installation via npm for local buildsXX
Native integration with browsers, frameworks and build toolsXXX
For testing onlyX

Components CDN and local build

The advantages of using components include the following for both CDN and local builds:

  • Use of HTML elements, such as <arcgis-map />, to encapsulate API logic so that functionality can be added with minimal code.
  • Use of JavaScript is optional, depending on requirements.
  • Enhances the portability of code between applications.

ES modules local build

The advantages of building ES modules locally include:

  • Uses native modules which are compatible with browsers, frameworks and build tools.
  • Certain API capabilities available server-side in node.js, for example, geometryEngine.

CDN (ESM)

The ESM CDN is for testing only, it is unbuilt and not optimized for module loading performance. For best performance with ES modules, build them locally.

CDN (AMD)

The advantages of using the AMD CDN include:

  • Modules are downloaded via optimized cloud caching.
  • Easy to update to a new version because it doesn't require rebuilding the application.

The disadvantages include:

  • The modules are not natively compatible with browsers, frameworks and build tools.
  • The modules require a separate AMD module loader or transpiling.

AMD local build (deprecated)

The are only a few reasons for building locally with AMD:

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

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