feat(migrate): add v8-to-v9 migration tool

[ShaneK]

Issue number: internal

---

What is the current behavior?

There's no tooling to help apps move across a major version of Ionic. Every breaking change in the v9 upgrade guide has to be found and applied by hand, across Angular, React, and Vue, with no way to tell which ones a given app is even affected by.

What is the new behavior?

Adds a new @ionic/migrate package: a standalone tool that scans an app, applies the breaking changes it can make safely, and prints a checklist of the ones that need manual rework, each with a file, line, and docs link. It detects the installed framework and major from package.json and selects only the migrations whose version range applies, so a project already on the target major does nothing.

Auto-fixes cover the Angular import and package bumps, CSS ~ prefix removal, standalone zoneless bootstrap, React Router v6 route rewrites and dep bumps, Vue Router 5 / Vue 3.5 bumps, and autocorrect="off". Report-only findings cover the rest (NgModule zoneless, legacy picker, ion-img, ion-nav router removal, RR6 semantic cases, Vue guard next()). TypeScript and TSX edits go through ts-morph; HTML and Vue templates use a quote-aware scanner so string literals and comments are left alone. Changed files are run through the project's own Prettier so the AST edits land as clean diffs.

The runner is single-shot by design (a project migrator isn't inherently idempotent - some cannot be due to the nature of their change, like the Angular import changes) and guards re-runs two ways: the version gate skips work once the @ionic/* bump has landed, and save() buffers text writes so the gate-closing package.json bump only hits disk if every migration and the ts-morph save succeed. It won't write to a dirty working tree or directory without git unless --force is passed, so git can be used to undo changes in case of emergency.

Does this introduce a breaking change?

• Yes
• No

Other information

Migrations are registered in src/migrations/index.ts; adding one is a new file under src/migrations/v<major>/ plus a fixture-backed test. The engine handles selection, ordering, git safety, formatting, and reporting.

Several new tests were added for migrations and a CI workflow was added that runs migration tests only when migration-related files were changed. When this is merged fully to main we can also make that check required to prevent breaking migration changes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ionic-framework	Ready	Preview	Jul 31, 2026 10:06pm

[brandyscarney]

Looking really good! Excited for this.

[brandyscarney]

Great work! Thanks for adding colors. 🎨

[thetaPC]

LGTM, left one actual request and the rest are suggestions

[thetaPC]

Please use inclusive language:

Suggested change

	lines.push(` see${cyan(entry.migration.docsUrl)}`);
	lines.push(` review${cyan(entry.migration.docsUrl)}`);

[ShaneK]

Done! a38222a

[thetaPC]

@ShaneK When I reran the command, it successfully blocked it but did print out "Ionic migrate: angular@9 (v9 -> v10, 0 migration(s))". Is there a check in case a dev tries to migrate to a version that doesn't exist?

[ShaneK]

@thetaPC in a38222a I added a check that'll prevent it from trying to upgrade to versions that don't have migrations