A real world ionic 4 migration
What the next five minutes reading will be about…
Read what it takes to migrate an ionic 3 app serving thousands of users to ionic 4 and where the “how tos” are not telling the whole truth.
Our motivation to upgrade
Our ionic3 app was out in the stores and running quite smoothly. Could there be a better point of time to break everything again?
After the transition of our code base to a monorepo we wanted to introduce proper tooling like nx workspace to support our work and make it easy for us to publish modules out of the monorepo. The downside of that was that we need to upgrade to (at least) angular v7 — not supported by ionic 3. And that was the start of our journey…
Starting our ionic 4 journey
If you do your homework and read about upgrading there are basically two things you come across:
- start with a blank ionic 4 app for the upgrade
- there are quite a few changes but its not that hard
For a major version upgrade, the transition from Ionic 3 to Ionic 4 is going to be relatively minor. [Josh]
To make a long story short — both things turned out different for us.
Our pre-work
To gain a better understanding what the upgrade would mean,we prototyped the migration with the aim to have a running app that enabled the user to login and views of the landing page. This was probably the single best thing we did along the migration process because it showed pretty much all the problems that occured later on.
Starting from scratch
Due to the number of classes we decided to (a) create an ionic4 app from scratch, but (b) do not re-create every single component. The main reason was that we wanted to keep our git history specially to allow easier DIFFs between the ionic 3 and 4 version in the case of bugs occurring after the upgrade.
Just a few changes
If you look at the (breaking) changes the list is actually not that long and none of the items are particularly difficult. Things like routing obviously had a big impact but then after all we did not really run into an issue that could not be resolved. What really “killed” us was the vast amount of changes that we had to implement. Essentially every single class needed treatment. Be it the fact that the import changed (search & replace all files is your friend) or simply that a sync method is now async. Another bump along the road: shadow dom. Certainly a great feature but quite cumbersome if you migrate an existing app or if you cannot style components that you were able to adjust in the past.
How did we tackle the upgrade?
Our setup might not be suitable for everyone but we were actually quite happy with the described approach.
- For the time being we created an `develop-ionic4` branch that was the base for all ionic4 changes.
- We moved all the source code into a new directory and started rebuilding the app in the “old” directory. This way the git history was persevered but at the same time we were able to build up a working app step by step.
- Each feature that we wanted to migrate was moved to the new folder. Once the “old” directory was empty we know: done — simple as that ;-)
- One of the challenges was to keep development on our “develop” branch on going. We had to label all “PRs” and, after the migration, added another week where we re-applied these changes to the ionic 4 version.
Things — that proofed to be useful
- Not creating every component from scratch really helped when we needed to debug errors after the migration caused by it.
- v4 migration tslint was a big helped in this regard.
- We chose not fix everything 100% during the migration. For certain issues, we decided that from a time-money-value perspective we would approach it later or even delete the feature/workaround/bugfixer.
- Resisting the temptation to refactor the whole code and at the same time collecting all the technical debts that we come across so that we were able to tackle them later proved to be very useful.
- Running a “test” migration for one core component was really efficient because during that process we came across 90% of the problems that we saw across the app later but without the time pressure we were facing during the real migration.
Things — we stumbled across
- While upgrading to ionic 4, we also switched from “UIWebView” to “WKWebView” which caused a hard to debug problem with our custom cordova plugin. This is certainly something we would approach in two steps the next time.
- With great features like shadow DOM also comes great pain if you don’t have access to all the attributes that we were modfiying previously.
What did it cost?
Estimations of a migration are probably always inaccurate but the following numbers might give you a good idea.
In total we migrated ~36.784 lines of typescript code with 2–3 people in about 3 months.
(Note: Development for our ionic3 app continued during that time — so folks were not doing ionic migration full time.)
Lessons learned
The migration itself worked quite well and all the individually changes where not that hard. BUT the vast amount of changes, meaning that not a single UI component stayed untouched, and the switch from sync to asny methods made this a tedious exercise not hard enought to enjoy it and not simple enough to hire a student…
Would we do it again? Probably yes — especially since the whole setup and coding is now much closer to the standard angular way and hopefully (fingers crossed) the next migration will be as easy as an angular migration from v7 to v8.
Want to share your migration experience?
