Skip to content

Commit be2918d

Browse files
liamdebeasiliamdebeasi
committed
add guide for NgModules
1 parent 640789b commit be2918d

File tree

1 file changed

+128
-13
lines changed

1 file changed

+128
-13
lines changed

‎docs/angular/build-options.md

Lines changed: 128 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -150,21 +150,21 @@ export class AppModule {}
150150

151151
## Migrating from Modules to Standalone
152152

153-
:::note
154-
This migration guide assumes the Angular components in your application are already standalone components. See [Migrating to Standalone](https://angular.io/guide/standalone-migration) if your Angular application is not already using standalone components.
155-
:::
153+
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.
154+
155+
Note that migrating to Ionic standalone components must be done all at the same time and cannot be done gradually. The Modules and Standalone approaches use two different build systems of Ionic that cannot be used at the same time.
156156

157-
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 as well as limitations to be aware of.
157+
### Using Ionic Standalone Components in Standalone-based Applications
158158

159-
### Steps to Migrate
159+
Follow these steps if your Angular application is already using the standalone architecture, and you want to use Ionic UI components as standalone components too.
160160

161161
1. Run `npm install @ionic/angular@latest` to ensure you are running the latest version of Ionic. Ionic UI Standalone Components is supported in Ionic v7.5 or newer.
162162

163163
2. Run `npm install ionicons@latest` to ensure you are running the latest version of Ionicons. Ionicons v7.2 brings usability improvements that reduce the code boilerplate needed to use icons with standalone components.
164164

165165
3. Remove the `IonicModule` call in `main.ts` in favor of `provideIonicAngular` imported from `@ionic/angular/standalone`. Any config passed to `IonicModule.forRoot` can be passed as an object to this new function.
166166

167-
```diff
167+
```diff title="main.ts"
168168
import { enableProdMode, importProvidersFrom } from '@angular/core';
169169
import { bootstrapApplication } from '@angular/platform-browser';
170170
import { RouteReuseStrategy, provideRouter } from '@angular/router';
@@ -200,7 +200,7 @@ bootstrapApplication(AppComponent, {
200200

201201
6. Add imports for each Ionic component in the Angular component where they are used. Be sure to pass the imports to the `imports` array on your Angular component.
202202

203-
```diff
203+
```diff title="app.component.ts"
204204
import { Component } from '@angular/core';
205205
+ import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';
206206

@@ -218,7 +218,7 @@ export class AppComponent {
218218

219219
7. If you are using Ionicons, define the icon SVG data used in each Angular component using `addIcons`. This allows you to continue referencing icons by string name in your component template. Note that you will need to do this for any additional icons added.
220220

221-
```diff
221+
```diff title="test.component.ts"
222222
import { Component } from '@angular/core';
223223
+ import { IonIcon } from '@ionic/angular/standalone';
224224
+ import { addIcons } from 'ionicons';
@@ -233,22 +233,137 @@ import { Component } from '@angular/core';
233233
})
234234
export class TestComponent {
235235
constructor() {
236-
addIcons({ alarm, logoIonic });
236+
+ addIcons({ alarm, logoIonic });
237237
}
238238
}
239239
```
240240

241241
8. Remove the following code from your `angular.json` file if present. Note that it may appear multiple times.
242242

243-
```diff
243+
```diff title="angular.json"
244244
- {
245245
- "glob": "**/*.svg",
246246
- "input": "node_modules/ionicons/dist/ionicons/svg",
247247
- "output": "./svg"
248248
- }
249249
```
250250

251-
### Limitations
251+
### Using Ionic Standalone Components in NgModule-based Applications
252+
253+
Follow these steps if your Angular application is still using the NgModule architecture, but you want to adopt Ionic UI components as standalone components now.
254+
255+
1. Run `npm install @ionic/angular@latest` to ensure you are running the latest version of Ionic. Ionic UI Standalone Components is supported in Ionic v7.5 or newer.
256+
257+
2. Run `npm install ionicons@latest` to ensure you are running the latest version of Ionicons. Ionicons v7.2 brings usability improvements that reduce the code boilerplate needed to use icons with standalone components.
258+
259+
3. Remove the `IonicModule` call in `app.module.ts` in favor of `provideIonicAngular` imported from `@ionic/angular/standalone`. Any config passed to `IonicModule.forRoot` can be passed as an object to this new function.
260+
261+
```diff title="app.module.ts"
262+
import { enableProdMode, importProvidersFrom } from '@angular/core';
263+
import { bootstrapApplication } from '@angular/platform-browser';
264+
import { RouteReuseStrategy, provideRouter } from '@angular/router';
265+
- import { IonicModule, IonicRouteStrategy } from '@ionic/angular';
266+
+ import { provideIonicAngular, IonicRouteStrategy } from '@ionic/angular/standalone';
267+
268+
import { routes } from './app/app.routes';
269+
import { AppComponent } from './app/app.component';
270+
import { environment } from './environments/environment';
271+
272+
if (environment.production) {
273+
enableProdMode();
274+
}
275+
276+
@NgModule({
277+
declarations: [AppComponent],
278+
- imports: [BrowserModule, IonicModule.forRoot(), AppRoutingModule],
279+
+ imports: [BrowserModule, AppRoutingModule],
280+
providers: [
281+
{ provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
282+
+ provideIonicAngular({ mode: 'ios' }),
283+
],
284+
bootstrap: [AppComponent],
285+
})
286+
export class AppModule {}
287+
```
288+
289+
4. Remove any references to `IonicModule` found elsewhere in your application.
290+
291+
5. Update any existing imports from `@ionic/angular` to import from `@ionic/angular/standalone` instead.
292+
293+
```diff
294+
- import { Platform } from '@ionic/angular';
295+
+ import { Platform } from '@ionic/angular/standalone';
296+
```
297+
298+
6. Add imports for each Ionic component in the NgModule for the Angular component where they are used. Be sure to pass the components to the `imports` array on the module.
299+
300+
```diff title="app.module.ts"
301+
import { enableProdMode, importProvidersFrom } from '@angular/core';
302+
import { bootstrapApplication } from '@angular/platform-browser';
303+
import { RouteReuseStrategy, provideRouter } from '@angular/router';
304+
- import { provideIonicAngular, IonicRouteStrategy } from '@ionic/angular/standalone';
305+
+ import { provideIonicAngular, IonicRouteStrategy, IonApp, IonRouterOutlet } from '@ionic/angular/standalone';
306+
307+
import { routes } from './app/app.routes';
308+
import { AppComponent } from './app/app.component';
309+
import { environment } from './environments/environment';
310+
311+
if (environment.production) {
312+
enableProdMode();
313+
}
314+
315+
@NgModule({
316+
declarations: [AppComponent],
317+
- imports: [BrowserModule, AppRoutingModule],
318+
+ imports: [BrowserModule, AppRoutingModule, IonApp, IonRouterOutlet],
319+
providers: [
320+
{ provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
321+
provideIonicAngular({ mode: 'ios' })
322+
],
323+
bootstrap: [AppComponent],
324+
})
325+
export class AppModule {}
326+
```
327+
328+
7. If you are using Ionicons, define the icon SVG data used in each Angular component using `addIcons`. This allows you to continue referencing icons by string name in your component template. Note that you will need to do this for any additional icons added. The `IonIcon` component should still be provided in the NgModule.
329+
330+
```diff title="test.component.ts"
331+
import { Component } from '@angular/core';
332+
+ import { addIcons } from 'ionicons';
333+
+ import { alarm, logoIonic } from 'ionicons/icons';
334+
335+
@Component({
336+
selector: 'app-root',
337+
templateUrl: 'app.component.html',
338+
styleUrls: ['app.component.scss'],
339+
})
340+
export class TestComponent {
341+
constructor() {
342+
addIcons({ alarm, logoIonic });
343+
}
344+
}
345+
```
346+
347+
```diff title="test.module.ts"
348+
import { NgModule } from '@angular/core';
349+
import { TestComponent } from './test.component';
350+
+ import { IonIcon } from '@ionic/angular/standalone';
252351

253-
1. Your application must already make use of standalone APIs. Using Ionic UI components as standalone components in an application that uses `NgModule` is not supported.
254-
2. Migrating to Ionic standalone components must be done all at the same time and cannot be done gradually. The Modules and Standalone approaches use two different build systems of Ionic that cannot be used at the same time.
352+
@NgModule({
353+
imports: [
354+
+ IonIcon,
355+
],
356+
declarations: [TestComponent]
357+
})
358+
export class TestComponentModule {}
359+
```
360+
361+
8. Remove the following code from your `angular.json` file if present. Note that it may appear multiple times.
362+
363+
```diff title="angular.json"
364+
- {
365+
- "glob": "**/*.svg",
366+
- "input": "node_modules/ionicons/dist/ionicons/svg",
367+
- "output": "./svg"
368+
- }
369+
```

0 commit comments

Comments
 (0)