Migrate an app to a different technology with AI

AI coding assistants can help migrate an app from another mapping library to the 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 , or to a different JavaScript framework or UI architecture. This workflow focuses on capturing existing behavior, defining migration requirements, and recreating the app in a new technology stack while preserving workflows, data access, accessibility, and user experience.

Choose a migration strategy

Consider a rewrite when the new architecture differs substantially and the requirements can be verified end to end. Otherwise, migrate incrementally—especially if production must continue or behavior is poorly documented. Define how old and new parts share state, preserve data and authentication, and support rollback.

The steps below describe a rewrite. For either approach, capture requirements and plan cutover and rollback first.

Create requirements with screenshots

Capture screenshots of the workflows, UI states, and layouts to preserve. Attach them to this prompt if your assistant supports images:

Do not edit the source app. Create a migration requirements document first.

Inventory:

- the source mapping platform and version, separately from the target SDK version
- the source framework and integration style
- for an ArcGIS Maps SDK for JavaScript source app, its version and component, widget, or mixed UI architecture (for other source apps, the equivalent library and architecture details)
- every data, service, WebMap, WebScene, basemap, proxy, and authentication URL
- user flows, map interactions, and surrounding UI behavior
- desktop, tablet, and mobile layouts
- accessibility requirements: keyboard access, focus, labels, status announcements, contrast, and reduced motion
- loading, empty, offline, permission, and service-error states
- provided screenshots and missing screenshots for these states

Write requirements at the location recorded in the project instructions:

- separate confirmed behavior from open questions
- name the target: <target framework or template>
- preserve the SDK version installed by the generated target project rather than copy the source platform version
- define which UI, behavior, accessibility, and data must be preserved
- list validation commands and required runtime checks

Do not generate code or edit application files.

Recreate the app

Keep the source app available until you have verified that the replacement meets the requirements.

Set up the app

Generate an @arcgis/create app for the target framework and hosting model. See Create a new app with AI for template guidance.

npx @arcgis/create -n migrated-arcgis-app -t <template>

Install dependencies and confirm the generated app starts:

cd migrated-arcgis-app
npm install
npm run dev

Iterate on the results

Review and correct the assistant’s requirements document before approving implementation. Give the assistant the approved requirements and screenshots with the prompt below:

Read the migration requirements recorded in the project instructions and the captured screenshots.

Recreate the app in the generated @arcgis/create project. Keep its framework and installed SDK version. The source platform version is migration context, not a target dependency. Preserve the approved data URLs, authentication, responsive behavior, accessibility, validation commands, and user flows.

Implement in small stages that match the requirements and screenshots. Replace older implementation patterns with supported target patterns.

After each stage, follow the shared validation checklist. Report commands, exit statuses, pass/fail results, and relevant failures. Summarize:

- what matches the requirements and screenshots
- remaining UI or behavior gaps
- screenshot states still needing verification

Review each stage yourself, compare it with the requirements and screenshots, and use the reported gaps and acceptance criteria to approve the next stage.

Plan cutover and rollback

Before switching users to the new app, agree on the approver, required checks, and URL or authentication-redirect changes. Where practical, test alongside the source app and move users in stages.

Keep the previous deployment available and define rollback conditions and steps. Verify both versions remain compatible with the services and authentication settings. Reverting code alone does not guarantee a working rollback.

Test the results

Ask the assistant to follow the shared validation checklist and the checks below. Review its report and the replacement app yourself, and complete checks it could not run before approving cutover. For a rewrite, include:

• Compare the UI, workflows, accessibility, and responsive layouts with the source app and screenshots.
• Verify the target SDK version, service and WebMap or WebScene URLs, basemap, and authentication against the requirements.
• Check cutover and rollback against the hosting and data configuration.
• If the result differs substantially from the requirements, revise the instructions or model choice and restart from the clean generated app.