docs(angular): deprecate IonicModule

cspell-wordlist.txt

@@ -33,6 +33,7 @@ autogrow
 automations
 autoplay
 Callout
+codemods
 comparewith
 composables
 engageable

docs/angular/build-options.md

@@ -5,7 +5,7 @@ import TabItem from '@theme/TabItem';
 
 Developers have two options for using Ionic components: Standalone or Modules. This guide covers both options as well as the benefits and downsides of each approach.
 
-While the Standalone approach is newer and makes use of more modern Angular APIs, the Modules approach will continue to be supported in Ionic. Most of the Angular examples on this documentation website use the Modules approach.
+The Standalone approach makes use of modern Angular APIs and is the recommended way to use Ionic. The Modules approach and its `IonicModule` are **deprecated** as of Ionic 9 and will be removed in a future major version. Existing apps continue to work, but new apps should use the Standalone approach, and existing apps should plan to migrate. Refer to [Migrating from Modules to Standalone](#migrating-from-modules-to-standalone).
 
 ## Standalone
 
@@ -17,7 +17,7 @@ Ionic UI components as Angular standalone components is supported starting in Io
 
 Developers can use Ionic components as standalone components to take advantage of treeshaking and newer Angular features. This option involves importing specific Ionic components in the Angular components you want to use them in. Developers can use Ionic standalone components even if their Angular application is NgModule-based.
 
-See the [Standalone Migration Guide](#migrating-from-modules-to-standalone) for instructions on how to update your Ionic app to make use of Ionic standalone components.
+Refer to the [Standalone Migration Guide](#migrating-from-modules-to-standalone) for instructions on how to update your Ionic app to make use of Ionic standalone components.
 
 **Benefits**
 
@@ -29,6 +29,10 @@ See the [Standalone Migration Guide](#migrating-from-modules-to-standalone) for
 
 1. Ionic components need to be imported into every Angular component they are used in which can be time consuming to set up.
 
+:::info Code splitting
+Ionic ships standalone components from a single entry point (`@ionic/angular`). Bundlers such as Webpack and esbuild cannot split code from a single entry point across separate chunks, so the Ionic components you import are included in the main bundle rather than in the chunk for the route or component where they are used. Unused components are still tree-shaken out of the build. Refer to the [code splitting tracking issue](https://github.com/ionic-team/ionic-framework/issues/28574) for details.
+:::
+
 ### Usage with Standalone-based Applications
 
 :::warning
@@ -361,6 +365,10 @@ Ionic Angular's standalone components use ES Modules. As a result, developers us
 
 ## Modules
 
+:::warning Deprecation Notice
+The Modules approach and its `IonicModule` are deprecated as of Ionic 9 and will be removed in a future major version. `IonicModule` remains fully functional in Ionic 9, so existing apps continue to work without changes. New apps should use the [Standalone](#standalone) approach, and existing apps should plan to migrate using the [migration guide](#migrating-from-modules-to-standalone).
+:::
+
 ### Overview
 
 Developers can also use the Modules approach by importing `IonicModule` and calling `IonicModule.forRoot()` in the `imports` array in `app.module.ts`. This registers a version of Ionic where Ionic components will be lazily loaded at runtime.
@@ -382,7 +390,7 @@ In the example below, we are using `IonicModule` to create a lazily loaded versi
 import { NgModule } from '@angular/core';
 import { BrowserModule } from '@angular/platform-browser';
 
-import { IonicModule } from '@ionic/angular';
+import { IonicModule } from '@ionic/angular/lazy';
 
 import { AppComponent } from './app.component';
 
@@ -399,7 +407,7 @@ export class AppModule {}
 :::tip
 Try our automated utility for migrating to standalone!
 
-See https://github.com/ionic-team/ionic-angular-standalone-codemods for instructions on how to get started. All issues related to the migration utility should be filed on the linked repo.
+Refer to the [standalone migration codemods](https://github.com/ionic-team/ionic-angular-standalone-codemods) for instructions on how to get started. All issues related to the migration utility should be filed on the linked repo.
 :::
 
 The Standalone option is newer than the Modules option, so developers may wish to switch during the development of their application. This guide details the steps needed to migrate.

docs/angular/platform.md

@@ -95,7 +95,21 @@ Below is a table listing all the possible platform values along with correspondi
 
 The function used to detect a specific platform can be overridden by providing an alternative function in the global [Ionic config](../developing/config). Each function takes `window` as a parameter and returns a boolean.
 
-```tsx
+<Tabs
+  groupId="framework"
+  defaultValue="angular"
+  values={[
+    { value: 'angular', label: 'Angular' },
+    { value: 'angular-standalone', label: 'Angular (Standalone)' },
+  ]}
+>
+<TabItem value="angular">
+
+```tsx title="app.module.ts"
+/*
+ * IonicModule is deprecated as of Ionic 9 and will be removed in a future major version.
+ * Refer to the "Angular (Standalone)" tab to use `provideIonicAngular()` instead.
+ */
 import { IonicModule } from '@ionic/angular/lazy';
 
 @NgModule({
@@ -119,6 +133,33 @@ import { IonicModule } from '@ionic/angular/lazy';
 })
 ```
 
+</TabItem>
+<TabItem value="angular-standalone">
+
+```ts title="main.ts"
+import { provideIonicAngular } from '@ionic/angular';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    ...,
+    provideIonicAngular({
+      platform: {
+        /** The default `desktop` function returns false for devices with a touchscreen.
+        * This is not always wanted, so this function tests the User Agent instead.
+        **/
+        'desktop': (win) => {
+          const isMobile = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(win.navigator.userAgent);
+          return !isMobile;
+        }
+      },
+    })
+  ]
+})
+```
+
+</TabItem>
+</Tabs>
+
 ```ts
 type PlatformConfig = {
   android?: ((win: Window) => boolean) | undefined;

docs/developing/config/global/index.md

@@ -27,6 +27,10 @@ window.Ionic = {
 <TabItem value="angular">
 
 ```tsx title="app.module.ts"
+/*
+ * IonicModule is deprecated as of Ionic 9 and will be removed in a future major version.
+ * Refer to the "Angular (Standalone)" tab to use `provideIonicAngular()` instead.
+ */
 import { IonicModule } from '@ionic/angular/lazy';
 
 @NgModule({

docs/developing/config/per-component/index.md

@@ -47,6 +47,10 @@ window.Ionic = {
 **Not recommended**
 
 ```ts
+/*
+ * IonicModule is deprecated as of Ionic 9 and will be removed in a future major version.
+ * Refer to the "Angular (Standalone)" tab to use `provideIonicAngular()` instead.
+ */
 import { IonicModule } from '@ionic/angular/lazy';
 
 @NgModule({

docs/developing/config/per-platform-fallback/index.md

@@ -14,6 +14,10 @@ import TabItem from '@theme/TabItem';
 <TabItem value="angular">
 
 ```ts title="app.module.ts"
+/*
+ * IonicModule is deprecated as of Ionic 9 and will be removed in a future major version.
+ * Refer to the "Angular (Standalone)" tab to use `provideIonicAngular()` instead.
+ */
 import { isPlatform, IonicModule } from '@ionic/angular/lazy';
 
 const getConfig = () => {

docs/developing/config/per-platform-overrides/index.md

@@ -14,6 +14,10 @@ import TabItem from '@theme/TabItem';
 <TabItem value="angular">
 
 ```ts title="app.module.ts"
+/*
+ * IonicModule is deprecated as of Ionic 9 and will be removed in a future major version.
+ * Refer to the "Angular (Standalone)" tab to use `provideIonicAngular()` instead.
+ */
 import { isPlatform, IonicModule } from '@ionic/angular/lazy';
 
 const getConfig = () => {

docs/developing/config/per-platform/index.md

@@ -20,6 +20,10 @@ See the [Angular Platform Documentation](../angular/platform) for the types of p
 :::
 
 ```ts title="app.module.ts"
+/*
+ * IonicModule is deprecated as of Ionic 9 and will be removed in a future major version.
+ * Refer to the "Angular (Standalone)" tab to use `provideIonicAngular()` instead.
+ */
 import { isPlatform, IonicModule } from '@ionic/angular/lazy';
 
 @NgModule({

docs/updating/9-0.md

@@ -115,6 +115,10 @@ Angular 22 raises the minimum Node.js version to `^22.22.3 || ^24.15.0 || ^26.0.
 
 Ionic 9 makes standalone components the default import path. Change lazy-loaded component imports from `@ionic/angular` to `@ionic/angular/lazy`. Change standalone component imports from `@ionic/angular/standalone` to `@ionic/angular`.
 
+#### IonicModule Deprecation
+
+`IonicModule` is deprecated in Ionic 9 and will be removed in a future major version. It remains fully functional, so no immediate action is required. When you are ready, migrate to `provideIonicAngular()`, which works in both standalone and NgModule-based apps. Refer to [Migrating from Modules to Standalone](/docs/angular/build-options.md#migrating-from-modules-to-standalone).
+
 #### CSS Imports
 
 Remove the `~` prefix from `@ionic/angular` CSS imports. Angular's current build pipeline no longer supports the webpack-loader prefix: