diff --git a/BREAKING.md b/BREAKING.md index 8076a0dc981..19dd275fb11 100644 --- a/BREAKING.md +++ b/BREAKING.md @@ -165,6 +165,12 @@ Ionic 9 requires Angular 18 or later. Angular 16 and 17 are no longer supported. Following industry standards, Ionic 9 makes standalone components the default import path. Standalone component imports have changed from `@ionic/angular/standalone` to `@ionic/angular`. Lazy-loaded component imports have changed from `@ionic/angular` to `@ionic/angular/lazy`. +**IonicModule Deprecation** + +`IonicModule` is deprecated in Ionic 9 and will be removed in a future major version. It remains fully functional in Ionic 9, so existing applications continue to work without changes. + +Applications should migrate to `provideIonicAngular()`, which works in both standalone and NgModule-based applications. For an NgModule-based app, replace `IonicModule.forRoot(config)` in the `imports` array with `provideIonicAngular(config)` in the `providers` array. Any config passed to `IonicModule.forRoot()` can be passed as an object to `provideIonicAngular()`. Refer to the [build options guide](https://ionicframework.com/docs/angular/build-options) for migration steps. + **Zoneless Change Detection by Default** Ionic 9 defaults to zoneless change detection. Angular 21 bootstraps zoneless out of the box, so a new Ionic 9 app on Angular 21 runs without Zone.js and requires no change-detection provider. The `ng add @ionic/angular` schematic no longer registers `provideZoneChangeDetection()`. diff --git a/docs/angular/testing.md b/docs/angular/testing.md index ccfe4de8edd..b73f391e3cf 100644 --- a/docs/angular/testing.md +++ b/docs/angular/testing.md @@ -82,6 +82,9 @@ If you need to add E2E tests that are only run on a specific version of the JS F Tests for lazy loaded Ionic UI components should only be added under the `/lazy` route. This ensures the `IonicModule` is added. +> [!CAUTION] +> The lazy loaded build, including `IonicModule`, is deprecated and will be removed in a future major version. New components should be tested as standalone components (see below). These lazy tests remain to verify that the deprecated build keeps working while it is still supported. + ### Testing Standalone Ionic Components Tests for standalone Ionic UI components should only be added under the `/standalone` route. This allows for an isolated environment where the lazy loaded `IonicModule` is not initialized. The standalone components use Stencil's custom element bundle instead of the lazy loaded bundle. If `IonicModule` is initialized then the Stencil components will fall back to using the lazy loaded implementation instead of the custom elements bundle implementation. diff --git a/packages/angular/README.md b/packages/angular/README.md index 7076172a9ff..e38d99b3f81 100644 --- a/packages/angular/README.md +++ b/packages/angular/README.md @@ -112,3 +112,6 @@ Ionic developers can access this by importing from `@ionic/angular`. This is where the lazy loaded component implementations live. Ionic developers can access this by importing from `@ionic/angular/lazy`. + +> [!CAUTION] +> The lazy loaded build, including `IonicModule`, is deprecated and will be removed in a future major version. New code should use the standalone components and `provideIonicAngular()` imported from `@ionic/angular`. diff --git a/packages/angular/lazy/src/index.ts b/packages/angular/lazy/src/index.ts index 4f271c6640d..ffa3409fdf2 100644 --- a/packages/angular/lazy/src/index.ts +++ b/packages/angular/lazy/src/index.ts @@ -43,7 +43,10 @@ export { ModalController } from './providers/modal-controller'; export { PopoverController } from './providers/popover-controller'; export { ToastController } from './providers/toast-controller'; -// PACKAGE MODULE +/* + * PACKAGE MODULE + * TODO(FW-7617): Remove the `IonicModule` export once the deprecated module is removed. + */ export { IonicModule } from './ionic-module'; export { diff --git a/packages/angular/lazy/src/ionic-module.ts b/packages/angular/lazy/src/ionic-module.ts index acd7745294b..a22b0cd038d 100644 --- a/packages/angular/lazy/src/ionic-module.ts +++ b/packages/angular/lazy/src/ionic-module.ts @@ -56,6 +56,11 @@ type OptInAngularFeatures = { useSetInputAPI?: boolean; }; +/** + * @deprecated `IonicModule` is deprecated and will be removed in a future major version. + * Use `provideIonicAngular()` instead, which works in both standalone and NgModule-based + * applications. Refer to https://ionicframework.com/docs/angular/build-options for migration steps. + */ @NgModule({ declarations: DECLARATIONS, exports: DECLARATIONS, @@ -63,7 +68,15 @@ type OptInAngularFeatures = { imports: [CommonModule], }) export class IonicModule { + /** + * @deprecated `IonicModule.forRoot()` is deprecated and will be removed in a future major version. + * Use `provideIonicAngular()` instead. Any config passed here can be passed as an object to that + * function. Refer to https://ionicframework.com/docs/angular/build-options for migration steps. + */ static forRoot(config: IonicConfig & OptInAngularFeatures = {}): ModuleWithProviders { + console.warn( + `[Ionic Warning]: IonicModule has been deprecated in favor of provideIonicAngular() and will be removed in a future major version. Refer to https://ionicframework.com/docs/angular/build-options for migration steps.` + ); return { ngModule: IonicModule, providers: [