Upgrading to Ionic 4
When StencilJS was announced, I was super excited that it was going to be at the core of the next version of Ionic. I couldn’t wait to jump in and began upgrading packages. Little did I know that I would be setting off on quite a difficult adventure. Rather than force everyone to repeat the problems I ran into, I decided to document the steps I took to make this work. This guide covers the minimal changes you will need to get your Ionic 2 or 3 app running as an Ionic 4 app. Based on the amount of time it took to migrate a fairly small app, I might recommend starting a new Ionic V4 app and bringing your pages over in a piecemeal fashion.
At the time of this blog, Angular 6 was on RC3. The steps I use will be based around that and version numbers for dependencies like RXJS may change if Angular 6 has already been released by the time you attempt to perform this conversion.
The new Ionic build system now defers to Angular CLI to do all the work. Make sure you have the latest version of the Angular CLI by running npm i @angular/cli@next -D. Add an .angular-cli.json file to the root of your Ionic project. A basic config like the one below should be enough to get you going.
We are going to use the Angular CLI to easily update all of the angular packages to version 6.
Run ng update @angular/cli --migrate-only --from=1 which will update the config file you just created to the new version.
You should now have an angular.json file. Now it’s time to install the latest version of Angular using ng update --next. This will give you the commands you need to run the update. In my case, it was ng update @angular/core --next . I also needed to add the --force flag since I had some incompatible packages that required Angular 5.
You will need to add the Ionic styling section to your new angular.json file under assets. Yours should look similar to the one below.
Uninstall the existing ionic-angular package. You won’t be needing @ionic/app-scripts either anymore.
Finally, you’re going to install @ionic/angular, @angular/router, @angular-devkit/build-angular, and also the new schematics package @ionic/schematics-angular. You’ll notice the addition of the router package. Ionic will start using Angular Routing beginning in version 4 to better support the usage of apps as PWA’s. You should have all the packages necessary to run your app now.
This next part took me a bit to figure out. The Ionic CLI will attempt to call the ionic:build task if it exists in your package.json. This is going to cause you problems because ionic-app-scripts no longer exists. Remove the ionic:build and ionic:serve tasks.
In ionic.config.js the project type needs updated to angular from ionic-angular.
Add a new tsconfig.app.json in your src folder.
At this point, you should be able to run ionic build! Unfortunately, you will still have a lot of build issues but we’ll go through fixing some of those.
We’ll start with the easiest one first. RXJS 6 has a fair amount of breaking changes but the team created a TSLint fixer to handle them. Follow the migration steps on the ReactiveX github page. If you run ionic build now, all of the RXJS related issues should be gone now.
Find and replace all ionic-angular imports in your code and change them to @ionic/angular.
In your index.html, you can remove all the references to vendor, polyfills, and main scripts since these will be injected by Webpack now. You can also remove the reference to main.css. Your root component will most likely be <ion-app>. This is no longer used and should be your root component instead. In your app.component.ts file, add a selector to the component definition and make sure to update your index.html file with the new selector. Finally, add a base tag <base href="/"> .
In you app.module, the IonicModule.forRoot method no longer takes your root component as a parameter so you can remove that. You’ll want to change the bootstrap to now be your app instead of IonicApp. The IonicErrorHandler has also been removed so you can remove that from providers.
One of the big changes to Ionic 4 is the change to routing. Ionic 4 now uses native Angular Routing with a bit of a twist. Instead of pushing components directly into ion-nav, you will need to map those components to routes. This makes it a lot easier to support building PWA’s natively. In this example, I’m going to just add the routes to a single module but you will want to add routes to each specific module so that you can support Lazy Loading.
Add a file like above and make sure you import it to your main module.
Because the new Ionic components are Stencil based, Angular will get confused trying to process them. You will need to add CUSTOM_ELEMENTS_SCHEMA to the schemas section of your Module. You will need to do this in all Modules that will contain ionic components.
Next, remove all references to IonicPage() since all pages are now just standard Angular components.
One part that I’m not going to cover in this article are all of the breaking changes introduced as part of the conversion to StencilJS. You might be saying to yourself, “Hey, I was using <button ion-button> and it was working just fine. What gives?.” This comes from Ionic’s (awesome) web components push. Previously, ion-button had been a directive that could be applied via Angular. Web Components can only be elements which is why the refactoring is necessary. It’s a bit of a pain to refactor the components but you are gaining some performance improvements since all of the Ionic components are running natively in the web view instead of via Angular. For a list of breaking changes, check out this guide.
At this point, you should be able to run ionic serve. If you have dependencies on Cordova and need to run Cordova in the browser, you will need to configure ssl.key and ssl.cert or try running ionic cordova run browser -lcs --ssl=false. The guide below explains how to do so. At the Time of this article, there was a bug with the CLI that prevented ionic cordova run from being able to work. The fix has been checked in and I will update this guide when it has been released to NPM.
I hope this guide has helped you move your app to Ionic 4. I am very excited to see the changes added like the StencilJS components and the Angular Router.
If you want to see an example, please check out the repo below. I tried to add commits in the relevant steps.
Please message me on Twitter if you have any questions!