Frequently Asked Questions

Refer to the Get started guide topic to learn how to install and set up the SDK. There are a variety of resources for coming up to speed on building apps with the SDK. For example:

• Try some of the 10-minute tutorials
• Play around with SDK samples
• Watch ArcGIS Maps SDK for JavaScript: Building an App with Components, ArcGIS Maps SDK for JavaScript: Programming Patterns and Best Practices, and explore other presentations on the JavaScript Maps SDK

There are many great, free resources out there for learning JavaScript. Some of our favorites are Codecademy, Free Code Camp, and MDN JavaScript tutorials.

Yes, the SDK’s ES modules and components are compatible with the latest versions of most modern frameworks and build tools such as Rollup, webpack and esbuild. For more information, see the Getting started guide page. If you are having issues with the ES modules when using them within frameworks or build tools, start by reviewing our Troubleshooting Guide. To ask questions or report issues use the Esri Community site. Configuration and troubleshooting questions about frameworks and bundlers should be directed to their respective repositories and communities.

Esri is fully committed to building standards-based web components that extend the core API of the JavaScript Maps SDK into reusable custom HTML elements, such as <arcgis-map></arcgis-map>.

As of version 5.0, all widgets have been deprecated and will be removed starting at version 6.0 (early 2027).

For more information, see Transition plan: widgets to components.

Yes, slots are supported as of version 4.34.

For learning about 3D basics in the JavaScript Maps SDK, check out the 3D Visualization with the ArcGIS Maps SDK for JavaScript Developer Summit technical session video. This session will walk you through some core concepts for setting up a 3D application, and then will demonstrate different ways you can visualize 3D data. To learn more about 3D visualization, check out these guide pages. There are also several 10 minute, step-by-step coding tutorials and samples: Display a scene tutorial and Scene component samples.

Yes, the JavaScript Maps SDK works with 3D scenes in the browser on your phone. All you need is a URL to your app to interact with your data in 3D. For additional information, see the Hardware Requirements page.

Working in 3D, you can incorporate real-world elements with your content such as variations in terrain and realistic rendering of trees, buildings, and subsurface geology. Learn about the different types of scene layers for displaying and analyzing 3D data with the JavaScript Maps SDK. You can also browse for ready-made example 3D scenes in the ArcGIS Living Atlas. There is a 3D Workflows for the Web technical session video where you learn about building sophisticated 3D apps that leverage modern browser technology to render your 2D features with 3D symbology.

Version 5.1 is planned for June 2026, and version 5.2 is planned for October 2026.

Over time, the SDK evolves to accommodate new features, browser advancements, performance improvements, and better API and component design. As part of this evolution, some existing functionality or programming patterns (APIs) will be removed in a future release.

When a feature, component, class, property, method, event, or pattern is marked as deprecated, it means:

• The functionality will be removed in a future major release (for example, deprecated in 5.0.0, removed at version 6.0.0).
• The functionality will continue to work and is supported throughout the current major version (5.x).
• The functionality typically will not receive new enhancements and may only receive critical bug fixes.

Deprecations are communicated through:

• Release notes
• API and Component references (for example, deprecation tags and notes in documentation)
• Console warnings at runtime
• Typescript as @deprecated, which shows up in IDEs as crossed out text

These signals are intended to give you time to migrate to the recommended alternative before the deprecated functionality is removed. Under semantic versioning, deprecated functionality is removed at the next major version (6.0). See ArcGIS Maps SDK for JavaScript is Moving to Semantic Versioning for details.

Before upgrading to a major version of the SDK, we recommend thoroughly reviewing the latest breaking changes section of the release notes.

Starting with 5.0.0, the SDK follows semantic versioning, which uses a version format of:

• MAJOR.MINOR.PATCH (for example, 5.1.3)

Each part of the version number communicates the type of changes you can expect:

• Patch (5.0.1 to 5.0.2): Bug fixes and internal improvements that do not change the public API. No breaking changes.
• Minor (5.0.0 to 5.1.0): New features, enhancements, and new APIs that are backward-compatible.
• Major (5.x to 6.0.0): Breaking changes, including the removal of deprecated APIs and other incompatible changes. Major versions may also introduce significant new features, architectural changes, or improvements that may not be backward-compatible.

This makes major upgrades a planned migration step, rather than something you need to handle during minor SDK updates. While we follow these guidelines as much as possible, there may be infrequent circumstances when we introduce changes without prior notice. For example, breaking changes related to browser security updates or beta features.

Production releases of the ArcGIS Maps SDK for JavaScript sometimes have one or more capabilities that are released with a beta label. If you try out a feature in beta and it meets your app’s requirements, you can use it in your app. Here is what the beta label means:

• We are interested in gathering feedback with respect to ease of use of the API and whether the functionality adequately meets developer use-cases.
• In some cases, aspects of the capability haven’t been implemented yet, for example it might not support all layer types yet. In those cases, limitations will be noted in the API reference.
• Beta functionality is tested but still provisional. The API, behavior and end-user experience might change based on feedback or an improved design.
• Configuration for some beta capabilities may not be saved to web maps and web scenes.
• If you later decide to upgrade your application to a new SDK version, there might be code changes required in order for the capability to continue to work properly (due to # 3 above).
• Esri’s standard policies for beta software can be found in the Master Agreement.

Production releases of the ArcGIS Maps SDK for JavaScript sometimes have one or more capabilities that are released with a “preview” label. Preview represents a stage between beta and general availability and gives developers the chance to use functionality prior to general availability.

The key distinction between beta and preview is that preview capabilities are already stable, production‑ready, and in the final stages of productization, whereas beta capabilities are still maturing and may still change. They also follow semantic versioning in the same way that general availability capabilities do, with breaking changes only introduced with major versions.

Capabilities are available in preview for a limited time, designed to encourage user adoption and facilitate valuable feedback before their transition to general availability. There are no additional license fees while in preview.

U.S. customers who are current on Maintenance are entitled to Esri Technical Support for capabilities in preview. Customers outside the U.S. should contact their local distributor for information about technical support policies.

Yes, the next version of the SDK is available for trying out new features and performing regression testing. For more information visit https://github.com/Esri/feedback-js-api-next.

The JavaScript Maps SDK works with supported versions of ArcGIS Enterprise - see the Product Life Cycle support page. For example, ArcGIS 10.6.1 was retired on January 1, 2024. Non-supported versions might still work to different degrees, but are not being tested (or supported) with the SDK.

Esri’s legacy JavaScript API, version 3.x retired on July 1, 2024. See the ArcGIS API for JavaScript, Version 3.x Retirement blog for more information.

The cleanest approach when migrating from 3.x to 5.x is to re-write apps due to the fundamental differences in the object model and programming patterns. While “4.x” might suggest an incremental release of 3.x, version 4.x in fact introduced a completely new API with modernized architecture, requiring apps to be rewritten using the new programming patterns. Version 5.x is a continued progression of this API, with the version number reflective of our move to semantic versioning. For more information, see Migrating from 3.x.

Yes, browsers impose a limit on the number of WebGL2 contexts per window (including all tabs). It is typically between 8 and 16, depending on the device. Each MapView or SceneView uses one WebGL2 context. When too many contexts are created and this limit is exceeded, the browser will close the oldest context and log a console warning: “Too many active WebGL contexts. Oldest context will be lost.” For example, if your application creates 17 views, the view with the oldest context will stop rendering.

Recommended actions:

• Dashboard-style applications need to set a maximum number of views that can be created.
• Ensure users are aware of this limit.

The SDK is only supported on WebGL2-enabled browsers. The list of supported browsers and versions can be found in the System Requirements. To test for WebGL2 support, open https://get.webgl.org/webgl2/.

Reasons for a computer or phone not supporting WebGL2 include it is disabled in a browser setting, outdated or incompatible hardware and drivers, or using an outdated browser version. To resolve the issue, update your browser to the latest version or try a different browser, ensure hardware acceleration is enabled in your browser’s system settings, and update your computer’s graphics drivers. Then restart the browser and restart the machine.

For the best web page load times and user experience use HTTP/2 or HTTP/3.

In some cases, you may need to locally host a version of the ArcGIS CDN. An example of this is when you are working in a restricted network environment with no internet access. You can also download and install the documentation which includes the references, tutorials, and samples. The documentation available for download is a snapshot from the release date of version 5.0 and will not include the latest sample updates, documentation fixes, etc.

• To download the ArcGIS Maps SDK for JavaScript and its documentation, navigate to download page.

No. The code for the ArcGIS Maps SDK for JavaScript cannot be modified. See the terms of use for more information.

No. Most CSP directives are supported and certified within the JavaScript Maps SDK. The JavaScript Maps SDK makes use of WebAssembly (Wasm), which requires the inclusion of wasm-unsafe-eval in the script-src directive. A worker-src directive should be set to allow blob:. If this value is not set, the worker code will run on the main thread.

No. In embedded scenarios, e.g. Microsoft PowerBI, Windows Store app, or Adobe Creative Cloud, a web server is not necessary for using the JavaScript Maps SDK.