AI coding assistants can help modernize an existing ArcGIS Maps SDK for JavaScript
When an SDK upgrade is also required, the migration strategy depends on API compatibility. Upgrade first when the target release supports the app’s existing APIs. Otherwise, migrate on a release that supports both widgets and components, validate the migration, and then upgrade to the target SDK version.
Inventory the app
Add the migration guide, widget transition plan, and view model roadmap to the project instructions, then ask the assistant to inventory the app:
Inventory this app before making changes.
List:
- the current ArcGIS Maps SDK for JavaScript version- the framework, package or CDN integration, and use of components, widgets, or both- the validation commands, noting missing tools instead of inventing commands- every import from @arcgis/core/widgets/* or widgets/support/*- directly imported or instantiated widget view models, widget.viewModel access, and custom logic that calls their methods or watches their properties- every view.ui.add, view.ui.remove, and view.ui.move call- each MapView or SceneView construction site- any manual esri/themes stylesheet reference- Editor customizations, including formSystem, featureFormViewModel, and attachmentsViewModel- files containing map business logic versus view and UI setup
For each view model dependency, consult https://developers.arcgis.com/javascript/latest/view-models/ and the version-matched API reference. Record an available public replacement or a reason to defer that part of the migration. Do not assume every view model has a replacement or can be removed with its widget.
Recommend one pass for a small migration or one UI area at a time for complex work. Flag a large rewrite better suited to https://developers.arcgis.com/javascript/latest/ai-assisted-development/migrate-between-technologies/.
Include the SDK version, framework, integration style, and validation commands in the output table. Write a Markdown inventory at the location recorded in the project instructions. Do not edit code yet.Review and correct the inventory before asking the assistant to edit application code. Approve the migration scope, including any deferred view model dependencies, and reuse the inventory in later prompts.
Migrate views and widgets
Widgets and components can coexist during migration. Ask the assistant to change map business logic only where the component API requires it.
Choose a readiness pattern that fits the app: viewOnReady() suits vanilla JavaScript and CDN examples, while arcgisViewReadyChange integrates with framework lifecycles, commonly in npm-based apps. The choice depends on lifecycle needs, not the package source alone. See Waiting for components or views to be ready.
Read the widget-migration inventory recorded in the project instructions. Keep its SDK version, framework, map business logic, validation commands, and migration scope.
For a small app, migrate the remaining views and widgets in one pass. For a complex app, migrate one view or UI area at a time and stop for review.
Replace MapView or SceneView containers with arcgis-map or arcgis-scene where needed. Wait for view readiness using viewOnReady() in vanilla JavaScript or CDN code, or register arcgisViewReadyChange early in the framework lifecycle. Keep event handlers safe to run again when the map changes. Follow the version-matched guidance at https://developers.arcgis.com/javascript/latest/watch-for-changes/.
Replace targeted widgets with matching components, preserving configuration. Use slot for in-map placement and reference-element for external UI. Remove related view.ui.add, view.ui.remove, or view.ui.move calls only after replacements work.
Keep any manual esri/themes stylesheet until no widgets remain and no MapView or SceneView is initialized programmatically, then remove it. Do not add new @arcgis/core/widgets imports or view.ui.add calls.
Follow each component's reference page under https://developers.arcgis.com/javascript/latest/references/map-components/, using the documentation version that matches the app. Migrate view model dependencies only to verified public replacements; retain and report supported dependencies deferred in the approved inventory. Migrate flagged Editor customizations deliberately, preserving compatible behavior. After each change, follow the shared validation checklist. Report commands, exit statuses, pass/fail results, relevant failures, and observed runtime and visual results.Review migration changes
Check these replacements while keeping @arcgis/core business logic unchanged unless the new API requires it:
| Widget-era pattern | Component-era pattern |
|---|---|
new MapView({ container, map, ... }) or new SceneView({ container, map, ... }) | <arcgis-map> or <arcgis-scene> element with attributes or properties |
view.ui.add(widget, "top-left") | Place the component inside the map with slot="top-left" |
| Widget outside the view | Use reference-element="my-map" to connect it to the map element |
await view.when() for map element access | await mapElement.viewOnReady() for vanilla JavaScript, or an early arcgisViewReadyChange handler in a framework lifecycle |
Manual esri/themes/light/main.css stylesheet | Remove it only after the last widget is gone and no MapView or SceneView is initialized programmatically. Component styles load automatically |
@arcgis/core/widgets/* imports | Matching entries from the map components reference |
See Basic implementation for a before-and-after example.
Ask the assistant to follow the shared validation checklist and the checks below. Review its report, the replacement table, and the app yourself before accepting the migration. Complete checks the assistant could not run. For widget migration, include:
- Compare UI placement, workflows, responsive layouts, and any Editor customizations with the original app.
- Check that every targeted widget was replaced. Scan the migrated scope for widget imports,
view.uicalls, and the other patterns listed above. Account for any retained view model imports against the approved inventory. - Verify stylesheet removal meets both conditions in the table.
- Check the scope against the inventory. Stop and replan if an incremental migration becomes a larger rewrite.