ArcGIS Maps SDK for JavaScript

Resolve the target first

Determine whether the app targets ArcGIS Online or a specific ArcGIS Enterprise version, then resolve the SDK version from the live Esri version matrix — https://developers.arcgis.com/javascript/latest/version-matrix/ — rather than assuming "latest." The Enterprise release pins the SDK version, which in turn pins Calcite.

Know the generation boundaries

These are not ordinary version steps — treat them as distinct products where noted:

• 3.x — retired 2024-07-01. Not a migration target.
• 4.x — a complete rewrite of 3.x, not an increment. Moving 3.x → 4.x is a rewrite.
• 5.x — continues 4.x under semantic versioning: minor bumps are backward-compatible, major bumps are breaking.
• Migrating 3.x → 5.x is a rewrite, not an upgrade.

Use ES modules or components — the AMD path is dead

4.31 was the last release of the arcgis-js-api AMD npm package; its AMD TypeScript declarations and @arcgis/cli are retired. Build with @arcgis/core ES modules or the components packages. Do not scaffold AMD.