Skip to content

docs(updating): document automated migration tool and zone.js polyfills setup for v9 #4605

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ShaneK wants to merge 1 commit into
base: major-9.0
Choose a base branch
from
+34 −1
Open

docs(updating): document automated migration tool and zone.js polyfills setup for v9 #4605

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 34 additions & 1 deletion docs/updating/9-0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<!-- TODO(FW-7579): finalize the published command at GA (npx @ionic/migrate vs bundling into @ionic/cli). -->

```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
Expand Down Expand Up @@ -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.
Expand Down
Loading