From f555314fd60e75da0480b046d4d51b2c0b0a62c3 Mon Sep 17 00:00:00 2001 From: ShaneK Date: Mon, 27 Jul 2026 11:34:05 -0700 Subject: [PATCH 1/4] 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/4] 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/4] 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: From 10feca7346dc5bc29851fe772b3f3a4782c937d2 Mon Sep 17 00:00:00 2001 From: ShaneK Date: Thu, 13 Aug 2026 10:00:03 -0700 Subject: [PATCH 4/4] docs(updating): correct migration tool run order and drop published-command TODO --- docs/updating/9-0.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/updating/9-0.md b/docs/updating/9-0.md index b3c88cb657..7027198858 100644 --- a/docs/updating/9-0.md +++ b/docs/updating/9-0.md @@ -16,8 +16,6 @@ For a **complete list of breaking changes** from Ionic 8 to Ionic 9, please refe 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. - - :::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. ::: @@ -26,15 +24,18 @@ Commit your work first. The tool writes changes in place and refuses to run on a 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. +After a run it prints a summary of what it fixed and what is left for you, formats the changed files with your project's Prettier, and, if it applied anything, reinstalls dependencies so `node_modules` matches the version bump. 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-format` skips the Prettier pass over the changed files. - `--no-install` skips the dependency reinstall. +Run `npx @ionic/migrate --help` for the full list. + 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