docs(angular): add zoneless change detection guide and update v9 upgrade guidance#4541
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
2 tasks
brandyscarney
requested changes
Jun 9, 2026
brandyscarney
left a comment
brandyscarney
left a comment
Member
There was a problem hiding this comment.
Looks great! Left some comments.
ShaneK
added a commit
to ionic-team/ionic-framework
that referenced
this pull request
Jun 9, 2026
Issue number: resolves #30804 --------- ## What is the current behavior? Currently, on `major-9.0`, `@ionic/angular` still defaulted to Zone.js. The `ng add` schematic registered `provideZoneChangeDetection()`, and `zone.js` was a required peer dependency on both `@ionic/angular` and `@ionic/angular-server`. Angular 21 bootstraps zoneless out of the box, so Ionic was actively opting new apps back into Zone.js. ## What is the new behavior? Ionic 9 now defaults to zoneless change detection while keeping Zone.js as a supported opt-in. The `ng add` schematic no longer registers `provideZoneChangeDetection()`, and `zone.js` is now an optional peer dependency on both `@ionic/angular` and `@ionic/angular-server`. ## Does this introduce a breaking change? - [X] Yes - [ ] No Apps that want to keep Zone.js on Angular 21 must opt back in with `provideZoneChangeDetection()` AND keep `import 'zone.js'` in their polyfills (Angular 21's default scaffold omits it). Under zoneless, state updated from async callbacks Angular doesn't wrap needs a signal or a `markForCheck()` call. Template bindings, `@HostListener`, reactive forms, and synchronous lifecycle-hook state are unaffected. Angular 18 through 20 keep Angular's Zone.js default and need no change. BREAKING.md is updated with the full migration path. ## Other information - Test apps run dual-mode for coverage: ng21 is zoneless, ng18-20 stay on Zone.js. Shared `base/` test pages use the new `assertZoneContext()` helper (`base/src/app/zone-assert.util.ts`), which asserts in-zone only when Zone.js is present, so the same pages pass in both modes. Current dev build (2026-06-08): ``` 8.8.9-dev.11781013468.1ed93da9 ``` Test app: https://ionic-framework-git-feat-zoneless-ionic1.vercel.app/angular/ Docs PR: ionic-team/ionic-docs#4541 Docs Preview URL: https://ionic-docs-git-feat-zoneless-v2-ionic1.vercel.app/docs/updating/9-0#zoneless-change-detection
brandyscarney
approved these changes
Jun 9, 2026
brandyscarney
left a comment
brandyscarney
left a comment
Member
There was a problem hiding this comment.
Thank you for updating this! Love the new structure.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Providing documentation related to zoneless Angular support in Ionic Framework