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.
Components | ESM local build | CDN (ESM) | |
---|---|---|---|
Reduced boilerplate code (CDN and local builds) | X | ||
Installation via npm for local builds | X | X | |
Native integration with browsers, frameworks and build tools | X | X | X |
For testing only | X |
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,
geometry
.Engine
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.