Upgrade your SDK version with AI

AI coding assistants can help upgrade an existing ArcGIS Maps SDK for JavaScript ArcGIS Maps SDK for JavaScript, previously known as ArcGIS API for JavaScript, is a developer product for building mapping and spatial analysis applications for the web. Learn more app to a newer SDK release. This workflow focuses on evaluating release notes, updating dependencies, identifying compatibility changes, and validating the app after the upgrade. Use it when moving between SDK versions, rather than when adding features or fixing issues within the current release.

Collect upgrade information

Current SDK version: 5.1

Ask the assistant to plan the upgrade before you approve dependency changes:

Before editing, inventory this app for an ArcGIS Maps SDK for JavaScript upgrade.

State:

- the current and target SDK versions
- the release-note URLs for every release crossed, including intermediate releases
- whether the app uses npm packages or the versioned js.arcgis.com CDN, and which packages or URLs must change together
- the validation commands and affected features to retest
- applicable deprecations, breaking changes, and removed APIs
- which widget migrations are prerequisites and which can follow the upgrade

Recommend one update or smaller steps based on review and rollback risk.

Write a Markdown inventory at the location recorded in the project instructions. Do not edit code yet.

Review and correct the inventory before approving dependency changes. Reuse it in later prompts.

For example, upgrading from 4.33 to 5.1 requires the 4.34, 5.0, and 5.1 release notes. Review each crossed release and its relevant patch entries. For a patch-only upgrade, read the entries after the installed patch through the target patch.

Update the version

Upgrade first only if the target version supports the app’s existing APIs. If the target version removes widgets the app uses, migrate them on a release supporting both architectures, validate, then upgrade.

Update npm dependencies

For npm-based apps, update related SDK packages together. Run the commands yourself or ask the assistant to apply the dependency changes you approved:

1. Use the project’s package manager and keep compatible runtime and component packages on the documented major and minor version.
2. Install the Calcite version required by the target @arcgis/map-components release’s peerDependencies. Calcite follows the SDK’s major and minor version from version 5.0. Upgrades from earlier SDK releases also change the Calcite major version.
3. Check tooling, plugin, and helper compatibility in their documentation.

For a basic npm map-components app, run the command below. Include any other compatible runtime or component @arcgis/* packages the app uses:

npm install \
@arcgis/core@~5.1.0 \
@arcgis/map-components@~5.1.0 \
@esri/calcite-components@~5.1.0

The ~ ranges allow patch updates within this major and minor version. For a different target, use its version and compatible dependencies. Check the resolved versions in the lockfile.

Update CDN URLs

For CDN-based apps, update the versioned script URL instead of running the npm installation command. Also update the version in esri/themes/.../main.css if widgets remain or the app creates a MapView or SceneView programmatically. Component-only apps do not need a separate SDK stylesheet. Make these edits yourself or ask the assistant to make them for the approved target version.

Run the codemod

For TypeScript apps using deprecated __esri types, refactor-out-esri-namespace converts those types to explicit @arcgis/core imports. It does not automate other upgrade work. Skip it for JavaScript apps.

Review and commit dependency and lockfile changes so the codemod starts from a clean working tree. Record unresolved upgrade failures. This commit does not mean the upgrade is complete. Check the @arcgis/codemod runtime requirements before running:

npx @arcgis/codemod run refactor-out-esri-namespace

Review the diff yourself and keep any codemod warnings for the assistant to address in the next step.

Resolve remaining changes

Ask the assistant to fix breaking changes and replace removed APIs with the prompt below. Supported deprecations can remain unless their removal is in scope. Have the assistant record them for follow-up, with widget migration as a separate task.

Read the upgrade inventory recorded in the project instructions. Keep its target version, release-note URLs, package or CDN configuration, affected features, deprecations, and migration order. Stop if prerequisite widget migrations are incomplete.

Resolve breaking changes and replace removed APIs required by the target. Record supported deprecations as follow-up work unless their removal is in scope. Keep supported deprecated widgets and migrate them separately. Apply the same distinction to any refactor-out-esri-namespace warnings.

Follow the update steps agreed in the inventory. Stop for review at each planned checkpoint.

After each change, follow the shared validation checklist. Report commands, exit statuses, pass/fail results, and relevant failure details. Stop for upgrade blockers or required validation failures. Report supported deprecation warnings separately. They do not themselves block the upgrade.

Do not refactor unrelated code, change package versions again, or start widget migration in this workflow.

Test the results

Ask the assistant to follow the shared validation checklist and the checks below. Review its report and the app yourself, and complete checks it could not run. For an upgrade, include:

• Test every affected feature in the inventory against the pre-upgrade app and the expected release-note changes.
• Confirm the resolved dependencies or CDN URLs match the target and no removed APIs remain in the upgraded scope.