Updating to Ionic 4
Updating from Ionic 3 to 4
This guide assumes that you have already updated your app to the latest version of Ionic 3. If you are using Ionic 1 or 2, Make sure to follow the Updating from Ionic 1 to 4 Guide instead.
For a complete list of breaking changes from Ionic 3 to Ionic 4, please refer to the breaking changes document in the Ionic Framework repository.
We suggest the following general process when migrating an existing application from Ionic 3 to 4:
- Generate a new project using the
blank
starter (see Starting an App) - Copy any Angular services from
src/providers
tosrc/app/services
- Services should include
{ providedIn: 'root' }
in the@Injectable()
decorator. For details, please see Angular provider docs.
- Services should include
- Copy the app's other root-level items (pipes, components, etc) keeping in mind that the directory structure changes from
src/components
tosrc/app/components
, etc. - Copy global Sass styling from
src/app/app.scss
tosrc/global.scss
- Copy the rest of the application, page by page or feature by feature, keeping the following items in mind:
- Emulated Shadow DOM is turned on by default
- Page/component Sass should no longer be wrapped in the page/component tag and should use Angular's
styleUrls
option of the@Component
decorator - RxJS has been updated from v5 to v6 (see RxJS Changes)
- Certain lifecycle hooks should be replaced by Angular's hooks (see Lifecycle Events)
- Markup changes may be required (migration tool available, see Markup Changes)
In many cases, using the Ionic CLI to generate a new object and then copying the code also works very well. For example: ionic g service weather
will create a shell Weather
service and test. The code can then be copied from the older project with minor modifications as needed. This helps to ensure the proper structure is followed. This also generates shells for unit tests.
Changes in Package Name
In Ionic 4, the package name is @ionic/angular
. Uninstall Ionic 3 and install Ionic 4 using the new package name:
$ npm uninstall ionic-angular
$ npm install @ionic/angular@v4-lts
While migrating an app, update the imports from ionic-angular
to @ionic/angular
.
Project structure
One of the major changes between an Ionic 3 app and an Ionic 4 app is the overall project layout and structure. In v3, Ionic apps had a custom convention for how an app should be set up and what that folder structure should look like. In v4, this has been changed to follow the recommended setup of each supported framework.
For example, if an app is using Angular, that project structure will be exactly what an Angular CLI app would be. This change, while not too difficult to accommodate, helps to keep common patterns and documentation consistent.
- Ionic 4
- Ionic 3
src/
├── app/
│ ├── about/
│ ├── home/
│ ├── app-routing.module.ts
│ ├── app.component.html
│ ├── app.component.spec.ts
│ ├── app.component.ts
│ └── app.module.ts
├── assets/
├── environments/
├── theme/
├── global.scss
├── index.html
├── karma.conf.js
├── main.ts
├── polyfills.ts
├── test.ts
├── tsconfig.app.json
└── tsconfig.spec.json
.gitignore
angular.json
ionic.config.json
package.json
tsconfig.json
tslint.json
src/
├── app/
│ ├── app.component.html
│ ├── app.html
│ ├── app.module.ts
│ ├── app.scss
│ └── main.ts
├── assets/
├── pages/
│ ├── about/
│ ├── home/
├── theme/
├── index.html
├── manifest.json
└── service-worker.js
.gitignore
ionic.config.json
package.json
tsconfig.json
tslint.json
The above comparison is an example of a v4 app's project structure. For developers with experience in a vanilla Angular project, this should feel really familiar.
There is a src/
directory that acts as the home for the app. This includes the index.html
, any assets, environment configuration, and any app-specific config files.
While migrating an app to take advantage of this new layout, it is suggested that a new project "base" is made with the CLI. Then, with the new project layout, migrate the features of the app piece by piece. Pages/components/etc. should be moved into the src/app/
folder.
Ensure your Ionic configuration file has the appropriate type
. The project type for v3 is ionic-angular
. The project type for v4 is angular
. If this value is incorrect, the CLI may invoke the incorrect build scripts.
See the following ionic.config.json
as an example:
{
"name": "my-app",
"type": "angular"
}
RxJS Changes
Between V3 and V4, RxJS was updated to version 6. This changes many of the import paths of operators and core RxJS functions. Please see the RxJS Migration Guide for details.
Lifecycle Events
With V4, we're now able to utilize the typical events provided by Angular. But for certain cases, you might want to have access to the events fired when a component has finished animating during its route change. In this case, the ionViewWillEnter
, ionViewDidEnter
, ionViewWillLeave
, and ionViewDidLeave
have been ported over from V3. Use these events to coordinate actions with Ionic's own animations system.
Older events like ionViewDidLoad
, ionViewCanLeave
, and ionViewCanEnter
have been removed, and the proper Angular alternatives should be used.
For more details, check out the router-outlet docs
Overlay Components
In prior versions of Ionic, overlay components such as Loading, Toast, or Alert were created synchronously. In Ionic v4, these components are all created asynchronously. As a result of this, the API is now promise-based.
// v3
showAlert() {
const alert = this.alertCtrl.create({
message: "Hello There",
subHeader: "I'm a subheader"
});
alert.present();
}
In v4, promises are used:
showAlert() {
this.alertCtrl.create({
message: "Hello There",
subHeader: "I'm a subheader"
}).then(alert => alert.present());
}
// Or using async/await
async showAlert() {
const alert = await this.alertCtrl.create({
message: "Hello There",
subHeader: "I'm a subheader"
});
await alert.present();
}
Navigation
In V4, navigation received the most changes. Now, instead of using Ionic's own NavController
, we integrate with the official Angular Router. This not only provides a consistent routing experience across apps, but is much more dependable. The Angular team has an excellent guide on their docs site that covers the Router in great detail.
To provide the platform-specific animations that users are used to, we have created ion-router-outlet
for Angular Apps. This behaves in a similar manner to Angular's router-outlet
but provides a stack-based navigation (tabs) and animations.
For a detailed explanation in navigation works in a V4 project, check out the Angular navigation guide.
Lazy Loading
Since Navigation has changed, the mechanism for lazy loading has also changed in V4.
In v3, a typical lazy loading setup worked like this:
// home.page.ts
@IonicPage({
segment: 'home'
})
@Component({ ... })
export class HomePage {}
// home.module.ts
@NgModule({
declarations: [HomePage],
imports: [IonicPageModule.forChild(HomePage)]
})
export class HomePageModule {}
However, in v4, lazy loading is done via the loadChildren
method of the Angular router:
// home.module.ts
@NgModule({
imports: [IonicModule, RouterModule.forChild([{ path: '', component: HomePage }])],
declarations: [HomePage],
})
export class HomePageModule {}
// app.module.ts
@NgModule({
declarations: [AppComponent],
imports: [
BrowserModule,
IonicModule.forRoot(),
RouterModule.forRoot([
{ path: 'home', loadChildren: './pages/home/home.module#HomePageModule' },
{ path: '', redirectTo: 'home', pathMatch: 'full' },
]),
],
bootstrap: [AppComponent],
})
export class AppModule {}