From 9817adeea235d5b905c38072aa39552c8440a47d Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Thu, 16 Jul 2026 15:59:06 -0700 Subject: [PATCH 1/2] docs(angular): deprecate IonicModule --- docs/angular/build-options.md | 16 +++++-- docs/angular/platform.md | 43 ++++++++++++++++++- docs/developing/config/global/index.md | 4 ++ docs/developing/config/per-component/index.md | 4 ++ .../config/per-platform-fallback/index.md | 4 ++ .../config/per-platform-overrides/index.md | 4 ++ docs/developing/config/per-platform/index.md | 4 ++ docs/updating/9-0.md | 4 ++ 8 files changed, 78 insertions(+), 5 deletions(-) diff --git a/docs/angular/build-options.md b/docs/angular/build-options.md index 928fa8c42e..191f79d035 100644 --- a/docs/angular/build-options.md +++ b/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. diff --git a/docs/angular/platform.md b/docs/angular/platform.md index 6b4644e01e..4ab6679690 100644 --- a/docs/angular/platform.md +++ b/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 + + + +```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'; }) ``` + + + +```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; + } + }, + }) + ] +}) +``` + + + + ```ts type PlatformConfig = { android?: ((win: Window) => boolean) | undefined; diff --git a/docs/developing/config/global/index.md b/docs/developing/config/global/index.md index c4399f2967..3bbb4dec58 100644 --- a/docs/developing/config/global/index.md +++ b/docs/developing/config/global/index.md @@ -27,6 +27,10 @@ window.Ionic = { ```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({ diff --git a/docs/developing/config/per-component/index.md b/docs/developing/config/per-component/index.md index ed5e82c709..b5135ba718 100644 --- a/docs/developing/config/per-component/index.md +++ b/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({ diff --git a/docs/developing/config/per-platform-fallback/index.md b/docs/developing/config/per-platform-fallback/index.md index fe9f073695..951e89fb84 100644 --- a/docs/developing/config/per-platform-fallback/index.md +++ b/docs/developing/config/per-platform-fallback/index.md @@ -14,6 +14,10 @@ import TabItem from '@theme/TabItem'; ```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 = () => { diff --git a/docs/developing/config/per-platform-overrides/index.md b/docs/developing/config/per-platform-overrides/index.md index 2aaf3db5c1..139c49f32d 100644 --- a/docs/developing/config/per-platform-overrides/index.md +++ b/docs/developing/config/per-platform-overrides/index.md @@ -14,6 +14,10 @@ import TabItem from '@theme/TabItem'; ```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 = () => { diff --git a/docs/developing/config/per-platform/index.md b/docs/developing/config/per-platform/index.md index 7a5b73f7d7..33ec4ac209 100644 --- a/docs/developing/config/per-platform/index.md +++ b/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({ diff --git a/docs/updating/9-0.md b/docs/updating/9-0.md index d4194966d7..7b1371290c 100644 --- a/docs/updating/9-0.md +++ b/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: From 87609ab58317447c9220fd0834b6ec0cb96698d4 Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Thu, 16 Jul 2026 16:07:40 -0700 Subject: [PATCH 2/2] chore(cspell): add codemods --- cspell-wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/cspell-wordlist.txt b/cspell-wordlist.txt index dacba1037f..9519c85b35 100644 --- a/cspell-wordlist.txt +++ b/cspell-wordlist.txt @@ -33,6 +33,7 @@ autogrow automations autoplay Callout +codemods comparewith composables engageable