Ionic Angular (v3)

Common errors

• ERROR Error: Uncaught (in promise): No provider for NavController!

  cause Attempting to use `NavController` in a component or service without proper injection, or in an Ionic v4+ project where it's no longer the primary navigation mechanism.
  fix In Ionic 3, ensure `NavController` is injected in the constructor of your page components. In Ionic 4+, replace `NavController` usage with the Angular Router (`RouterModule`, `Router`, `ActivatedRoute`) for navigation, and `ion-router-outlet` for stack-based navigation.

• Error: Template parse errors: 'my-custom-component' is not a known element:

  cause This error in Ionic 3 typically means a custom component is used in a page's template but is not declared in the corresponding page's `NgModule` or the `AppModule`, especially problematic with lazy loading.
  fix Ensure that any custom components are correctly declared in an `NgModule` (e.g., a shared `ComponentsModule`) and that this module is imported into the `NgModule` of any page that uses these components. For lazy-loaded pages with `@IonicPage`, their `page.module.ts` must import modules containing shared components.

• ERROR in src/app/app.module.ts(XX,YY): error TS2307: Cannot find module 'ionic-angular'

  cause This error occurs if the `ionic-angular` package is not installed or incorrectly referenced in an Ionic 3 project. It can also appear if attempting to import from `ionic-angular` in an Ionic 4+ project, which uses `@ionic/angular` instead.
  fix For Ionic 3 projects, run `npm install ionic-angular@3.9.10 --save`. For Ionic 4+ projects, update all imports from `ionic-angular` to `@ionic/angular` and ensure `@ionic/angular` is installed.

• Page has a @IonicPage decorator, but it does not have a corresponding "NgModule"

  cause In Ionic 3, the `@IonicPage()` decorator for lazy loading requires that the page also has its own dedicated Angular module file (e.g., `home.module.ts`) which imports `IonicPageModule.forChild(HomePage)`.
  fix Ensure that every page decorated with `@IonicPage()` has an accompanying `page.module.ts` file with a properly configured `@NgModule` that imports `IonicPageModule.forChild(YourPage)`. Alternatively, if lazy loading is not desired, remove the `@IonicPage()` decorator and import the page directly into `AppModule`.

Warnings

• breaking The `ionic-angular` package (Ionic v3) is deprecated and has been entirely replaced by `@ionic/angular` (Ionic v4+). This transition involved a fundamental architectural shift from tightly-coupled Angular components to framework-agnostic Web Components, necessitating significant refactoring for migration.
  Fix: Migrate your project to the modern Ionic Framework (v4+) using the `@ionic/angular` package. This typically involves generating a new Ionic v4+ project and gradually migrating components, services, and styling. Key changes include switching from `NavController` to Angular Router, replacing `@IonicPage` lazy loading with standard Angular lazy loading, and updating component markup.
• breaking Ionic 3's navigation system, based on `NavController`, is incompatible with Ionic 4+ which fully embraces the Angular Router. This means `navCtrl.push()` and `navCtrl.setRoot()` patterns are deprecated in the modern framework.
  Fix: For Ionic 4+ applications, use the Angular Router for all navigation, leveraging `ion-router-outlet` for Ionic-specific animations and stack management. Refactor `NavController` calls to `router.navigate()` or `navController.navigateForward()` (from `@ionic/angular`).
• breaking The `@IonicPage` decorator, central to Ionic 3's lazy loading and deep linking, was removed in Ionic 4. Ionic 4+ adopts standard Angular routing and module-based lazy loading.
  Fix: Remove `@IonicPage` decorators and ensure all pages/components are imported via standard Angular modules (`NgModule`) and lazy-loaded via the Angular Router's `loadChildren` property. Each lazy-loaded page in Ionic 3 typically had its own `page.module.ts` file; in Ionic 4+, this is aligned with standard Angular module bundling.
• gotcha Ionic 3 applications are tightly coupled with older Angular versions (typically 4 or 5) and specific TypeScript versions. Attempting to upgrade Angular or TypeScript dependencies independently can lead to compilation errors (e.g., 'Module has no exported member Renderer') due to API incompatibilities.
  Fix: Maintain the specific Angular, TypeScript, and `@ionic/app-scripts` versions recommended for Ionic 3.9.10 projects. If modern Angular features are required, a full migration to Ionic 4+ is necessary.
• gotcha Ionic 3 projects often relied on Cordova for native device features. While Cordova is still supported, the Ionic team actively promotes Capacitor as the modern native runtime, offering better integration with web standards and broader framework support.
  Fix: When migrating or starting new projects, consider using Capacitor instead of Cordova for native functionality. Capacitor provides a more future-proof and integrated solution within the Ionic ecosystem.

Install

• npm install ionic-angular npm
• yarn add ionic-angular yarn
• pnpm add ionic-angular pnpm

Imports

• IonicModule
  wrong:

  import { IonicModule } from '@ionic/angular'; // Incorrect for Ionic 3

  correct:

  import { IonicModule } from 'ionic-angular';

  `IonicModule.forRoot(MyApp)` was used in the root `AppModule` to configure the Ionic app in v3.
• NavController
  wrong:

  import { NavController } from '@ionic/angular'; // Incorrect for Ionic 3, uses Angular Router directly in v4+

  correct:

  import { NavController } from 'ionic-angular';

  The primary service for imperative navigation in Ionic 3, managing the navigation stack.
• IonicPage
  wrong:

  import { Component } from '@angular/core'; // `@IonicPage` is a specific Ionic decorator, not standard Angular

  correct:

  import { IonicPage } from 'ionic-angular';

  Decorator used in Ionic 3 to enable lazy loading for pages and configure deep linking. It requires a corresponding page module.

Quickstart

Demonstrates a basic Ionic 3 page component using `NavController` for navigation and the `IonicPage` decorator for lazy loading, typical of Ionic v3 application structure.

import { Component } from '@angular/core';
import { NavController, IonicPage } from 'ionic-angular';

@IonicPage({
  segment: 'home-page'
})
@Component({
  selector: 'page-home',
  templateUrl: 'home.html'
})
export class HomePage {
  constructor(public navCtrl: NavController) {}

  // Example of navigating to another lazy-loaded page by its string name
  goToAboutPage() {
    this.navCtrl.push('AboutPage', { param1: 'value1' });
  }

  // Example of setting a new root page
  goToRootPage() {
    this.navCtrl.setRoot('WelcomePage');
  }

  // An example of Ionic 3 lifecycle hook
  ionViewDidLoad() {
    console.log('HomePage did load!');
  }
}

// In app.module.ts (simplified)
// import { IonicApp, IonicErrorHandler, IonicModule } from 'ionic-angular';
// @NgModule({
//   declarations: [MyApp],
//   imports: [IonicModule.forRoot(MyApp)],
//   bootstrap: [IonicApp],
//   entryComponents: [MyApp],
//   providers: [{provide: ErrorHandler, useClass: IonicErrorHandler}]
// })
// export class AppModule {}

// For a lazy-loaded page 'AboutPage', it would have its own about.module.ts:
// import { NgModule } from '@angular/core';
// import { IonicPageModule } from 'ionic-angular';
// import { AboutPage } from './about';
// @NgModule({
//   declarations: [AboutPage],
//   imports: [IonicPageModule.forChild(AboutPage)],
//   exports: [AboutPage]
// })
// export class AboutPageModule {}