feat(angular): deprecate IonicModule

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()`.

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 and its `IonicModule` are 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.

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 and its `IonicModule` are deprecated and will be removed in a future major version. New code should use the standalone components and `provideIonicAngular()` imported from `@ionic/angular`.

packages/angular/lazy/src/index.ts

@@ -43,7 +43,12 @@ export { ModalController } from './providers/modal-controller';
 export { PopoverController } from './providers/popover-controller';
 export { ToastController } from './providers/toast-controller';
 
-// PACKAGE MODULE
+/*
+ * PACKAGE MODULE
+ * `IonicModule` is deprecated and will be removed in a future major version.
+ * Use `provideIonicAngular()` from `@ionic/angular` instead. The deprecation is
+ * declared on the class itself, so consumers importing it here see the notice.
+ */
 export { IonicModule } from './ionic-module';
 
 export {

packages/angular/lazy/src/ionic-module.ts

@@ -56,14 +56,27 @@ 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,
   providers: [ModalController, PopoverController],
   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<IonicModule> {
+    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: [