From f555314fd60e75da0480b046d4d51b2c0b0a62c3 Mon Sep 17 00:00:00 2001 From: ShaneK Date: Mon, 27 Jul 2026 11:34:05 -0700 Subject: [PATCH 1/3] docs(updating): document automated migration tool and zone.js polyfills setup for v9 --- docs/updating/9-0.md | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/updating/9-0.md b/docs/updating/9-0.md index 37e18ebd30..4f1104c4bf 100644 --- a/docs/updating/9-0.md +++ b/docs/updating/9-0.md @@ -12,6 +12,31 @@ This guide assumes that you have already updated your app to the latest version For a **complete list of breaking changes** from Ionic 8 to Ionic 9, please refer to [the breaking changes document](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md#version-9x) in the Ionic Framework repository. ::: +## Automated Migration + +Before working through the changes below by hand, you can run the Ionic migration tool. It scans your app, applies the mechanical breaking changes it can make safely, and prints a checklist of the ones that need manual work, each with a file, a line, and a link back to this guide. It reads your framework and version from `package.json`, so it only applies the changes that affect your app. + + + +```shell +npx @ionic/migrate +``` + +:::warning +Commit your work first. The tool writes changes in place and refuses to run on a dirty working tree, or a project without git, unless you pass `--force`, so git is your undo. +::: + +After a run it reinstalls dependencies to match the version bump, then prints a summary of what it fixed and what is left for you. + +Useful options: + +- `--dry-run` reports what would change without writing anything. +- `--check` reports only and exits non-zero if any migration is still pending, for use in CI. +- `--force` writes even if the working tree is dirty or the project is not a git repository. +- `--no-install` skips the dependency reinstall. + +The tool is single-shot. Once it bumps your `@ionic/*` version, a re-run detects the new major and does nothing, so run it once per major upgrade and review the diff before committing. + ## Getting Started ### Angular @@ -72,12 +97,20 @@ platformBrowserDynamic() .catch((err) => console.error(err)); ``` -Either way, also confirm `zone.js` is listed in the `polyfills` array in `angular.json`. Angular 21 and later default scaffolds omit it: +Either way, also confirm `zone.js` is still loaded, since Angular 21 and later default scaffolds omit it. Add it back through whichever polyfills setup your project uses. + +If `angular.json` lists polyfills as an array, include `zone.js`: ```json title="angular.json" "polyfills": ["zone.js"] ``` +If your project uses a polyfills file instead (for example, Ionic starters set `"polyfills": "src/polyfills.ts"`), import it there: + +```ts title="src/polyfills.ts" +import 'zone.js'; +``` + #### OnPush Change Detection on Angular 22 Angular 22 changes the default change detection strategy to `OnPush` for components that don't declare one. Combined with the zoneless default above, component state you mutate as a plain field from an Ionic lifecycle hook (`ionViewWillEnter`, and so on) no longer re-renders on its own. From b9450987f94b0fed2c0207a557e0441d343236e1 Mon Sep 17 00:00:00 2001 From: Shane Date: Tue, 28 Jul 2026 08:19:10 -0700 Subject: [PATCH 2/3] docs(v9): phrasing improvement Co-authored-by: Brandy Smith --- docs/updating/9-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/updating/9-0.md b/docs/updating/9-0.md index 4f1104c4bf..8d9e998479 100644 --- a/docs/updating/9-0.md +++ b/docs/updating/9-0.md @@ -14,7 +14,7 @@ For a **complete list of breaking changes** from Ionic 8 to Ionic 9, please refe ## Automated Migration -Before working through the changes below by hand, you can run the Ionic migration tool. It scans your app, applies the mechanical breaking changes it can make safely, and prints a checklist of the ones that need manual work, each with a file, a line, and a link back to this guide. It reads your framework and version from `package.json`, so it only applies the changes that affect your app. +Before manually working through the changes below, you can run the Ionic migration tool. It scans your app, automatically applies the breaking changes that can be safely migrated, and prints a checklist of the remaining updates that require manual work. Each item includes the affected file, line number, and a link to the corresponding section of this guide. Because the tool reads your framework and version from `package.json`, it only applies migrations that are relevant to your app. From 5fc19313dd29dac8f3c2e3e5828e44de899fdcd9 Mon Sep 17 00:00:00 2001 From: ShaneK Date: Tue, 28 Jul 2026 08:21:17 -0700 Subject: [PATCH 3/3] docs(v9): updating order of paragraphs for clarity --- docs/updating/9-0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/updating/9-0.md b/docs/updating/9-0.md index 4f1104c4bf..78e7115389 100644 --- a/docs/updating/9-0.md +++ b/docs/updating/9-0.md @@ -18,14 +18,14 @@ Before working through the changes below by hand, you can run the Ionic migratio -```shell -npx @ionic/migrate -``` - :::warning Commit your work first. The tool writes changes in place and refuses to run on a dirty working tree, or a project without git, unless you pass `--force`, so git is your undo. ::: +```shell +npx @ionic/migrate +``` + After a run it reinstalls dependencies to match the version bump, then prints a summary of what it fixed and what is left for you. Useful options: