The Ionic 4 Migration Survival Guide

The Ionic Framework 4.0.0 Beta is officially available! Make sure to check out the official documentation, but I’ve also got a whole lot of content for you to check out below as well.

Although the alpha has technically been available for some time now for those who wanted to jump on board early, the official beta release is when a lot more people will want to start switching over. The beta release comes with official documentation and guidance from the Ionic team, and it indicates that although there may still be some bugs/issues, the framework is mostly stable and ready for use.

In my view, the migration from Ionic 3 to Ionic 4 is the most significant in the frameworks history, and it sets a course for Ionic that likely will not be deviated from for years to come. I say significant in the sense that it is of great importance/benefit, the actual work required to transition from Ionic 3 to Ionic 4 is much smaller than that of previous updates to the framework.

The purpose of this article will be to collate a lot of the resources that I have been creating to help people transition to Ionic 4 in an organised and digestible manner. I will be listing resources in a step-by-step style guide to first help you understand the general concepts, and then work through to the specifics of updating applications. I will also be including official resources from the Ionic team as they become available, as well as other resources that might be relevant.

I will also be releasing a massive update to my book Building Mobile Apps with Ionic & Angular to reflect all of the changes for Ionic 4 shortly after the beta of Ionic 4 is officially released (I’ve spent the previous 2 months pre-emptively updating everything, so it is mostly already done). If you are looking for an in-depth premium resource for getting up to speed with Ionic 4 then you might be interested in checking it out. Anybody who has already purchased the book will get this update for free (updates to the book are always free).

I will continue to update this article as more resources become available.

1. General Concepts

It is helpful to have a general understanding of the high-level conceptual changes in Ionic 4. The following resources will help explain why certain changes are being made, and the benefits they offer:

Key points:

Although a lot of changes are happening behind the scenes, the way you build applications currently will mostly remain the same
Instead of being built on top of Angular, Ionic is now its own independent web component library that can be used with any framework (or without any framework at all)
Although most Ionic applications will still use Angular, Angular is no longer required to create Ionic applications
Ionic web components primarily provide the user interface for the application, whilst frameworks like Angular, Vue, or React will provide the structure/logic
Web components are like Angular components, except that they are native to the browser and can be used anywhere (with or without a framework)
Stencil is a tool Ionic uses to build their web components, and you can build your own web components with it if you want, but you do not need to use Stencil in order to use Ionic
Ionic 4 will bring performance improvements, but it is important to remember that your own code usually has the biggest impact on performance

2. Architectural Changes

For people building Ionic/Angular applications, the new version of Ionic will be paired with the latest version of Angular. With previous versions of Ionic, Ionic has kind of been its own special flavour of Angular. Now, there is more focus on letting Angular drive the bus and adding Ionic’s web components to that. In other words, an Ionic/Angular application will now mostly just be a standard Angular application with Ionic components added to it (rather than an Ionic-ised version of an Angular project).

This will mean there will be slight changes to the overall structure of the application in terms of where you will find files and folders and naming conventions. Once the beta is released, I will be updating this section with a video talking through the new project structure.

Key points:

Ionic/Angular applications will now more closely follow a standard Angular project structure
The overall project structure will still look very similar to previous versions of Ionic

As I mentioned in the last section, there is now a focus on following Angular conventions for an Ionic/Angular application (rather than Ionic doing things their own way). The most notable instance of this is the switch to using Angular routing for navigation. It will still be possible to use the old push/pop style of navigation in Ionic 4, so you don’t need to make these navigation changes to your application just yet if you don’t want to.

However, there are benefits to switching to using Angular routing for navigation, most notably that using Angular routing is required in order to use lazy loading (since the @IonicPage decorator has now been removed). The resources in this section will help you understand how Angular routing works, and how to switch an existing Ionic application to use Angular routing:

Key points:

Angular routing uses URL based navigation, rather than pushing and popping from a navigation stack
Using Angular routing involves creating “routes” that are linked to pages/components in your application
Ionic push/pop navigation will still be available, but it is recommended to move to Angular routing
Moving to Angular routing will likely be the change that requires the most significant amount of work in migrating your application

4. Styling Changes

There are a few changes in Ionic 4 that will impact the way you style/theme your applications. One of the most notable changes is that Ionic components now use CSS4 variables, which for most people will mean there will be a slightly different method for specifying theme colours. Another change is the switch to using “slots” in place of attributes like item-left or end in order to position and style Ionic components.

These are not the only changes in regard to styling your applications. Check out the following resources to get up to speed:

Key points:

CSS4 variables will now be used, but SASS is still available
Since CSS4 variables are supported natively by the browser, changes to these variables can be made at runtime
Ionic components will utilise Shadow DOM, which provides a way to isolate the styling of components from the rest of the application
The new version of Ionicons comes with support for supplying your own graphics for icons

5. Moving to Capacitor (Optional)

Capacitor is a new native bridge which fulfills the same role that Cordova does currently, but it has been built by the Ionic team with features that they feel are important. You can choose to use either Cordova or Capacitor with Ionic 4, and perhaps the articles below about Capacitor can help you decide if it is something you might be interested in.

Personally, I’ve been enjoying Capacitor a lot and have switched to using it for all of my projects. The good thing about Capacitor is that it requires very few changes – since most Cordova plugins work in Capacitor, integration is quite easy.

Key points:

Capacitor is a new native bridge that fulfills the same role as Cordova
Capacitor is aiming to be a runtime that allows a single application to work seamlessly on multiple platforms (iOS, Android, PWA, Electron)
Capacitor has its own set of Core APIs that you can use, but you can also use most existing Cordova plugins in Capacitor
Capacitor is aiming to make it easier/more approachable to access native code and integrate native features

6. Migrating an Ionic 3 Application to Ionic 4

Finally, we come to the part where we actually convert an Ionic 3 application into an Ionic 4 application. I have done this quite a few times now and my personal recommendation is to create a fresh Ionic 4 application and port your code over little by little. Since there are so few changes required to the code you write, but a lot of changes to the general architecture of the application and its dependencies, I find that it is much simpler to just move the code over into a new project rather than trying to update all of the dependencies and structure in place.

I wrote about my experiences and the process I use in this tutorial: My Method for Upgrading From Ionic 3 to Ionic 4.

You may prefer to take a different approach, but that is what has been working well for me. I believe the Ionic team is also working on a tool to help people upgrade their applications (this won’t upgrade the application for you, but rather highlight potential issues for you as you do the upgrade yourself) – I will update this post with a link to the tool if/when it becomes available.

Summary

The release of Ionic 4 does bring about some exciting new features, and greatly expands the possibilities of what is possible with Ionic. Although the upgrade process does not change nearly as much as has been changed in previous updates, it will still likely take a bit of time to understand the changes and then implement them.

The great thing about this move to web components is that, in future, the only real changes/upgrades that are going to be required will be for the framework you are using Ionic with (if you choose to use one). As Angular updates in the future – or React, or whatever other frameworks you might be using – you would need to update your applications to be compatible with those framework updates, but as for Ionic, nothing much should change at all.

1. General Concepts

2. Architectural Changes

3. Navigation Changes

4. Styling Changes

5. Moving to Capacitor (Optional)

6. Migrating an Ionic 3 Application to Ionic 4

Summary