With Ionic 3 we can change our Ionic apps to use lazy loading, which will significantly boost our performance. But we have to go through a few steps to migrate our old projects, which can get quite out of hand if you have a big project.

In this quick win we will go through the needed steps to upgrade your Ionic 2.x app to Ionic 3 so you can make use of Ionic lazy loading as well. I’ll also give you a script to automate most of the work in one step, if you have followed the general Ionic coding guidelines inside your app before!

1. Update Dependencies

First of all we need to update our package.json to use the new Ionic and Angular versions. Overall, you need to update the dependencies and devDependencies, but be careful not to replace other existing packages your app needs. Also, if you now already upgrade Ionic Native you have another part to take care of, so be aware which Ionic Native version you use!

Anyway, the updated fields of the file should look like this:

After updating this file, make sure to also update your packages by simply running:

Now your app might still work, but it’s not using lazy loading which we actually want, so follow the next steps to get this working in your app.

2. Create Modules for Pages & Use IonicPage

With Ionic 2 we had a folder for each page, with 3 files like in the image below.

Inside every of these folders we need to create a new file of the type NAME.module.ts, so the first file I would create inside the image is home-tabs.module.ts.

This new module file should look like this (if we follow the naming inside the image):

Nothing fancy, but we have to create this module file (with different names) for every page our old Ionic 2 app has!
Actually, near the end you will find a script that will do it for you if you have followed the general Ionic 2 coding and naming standards.

Next to creating this new module for every page, we also have to add a decorator to each page file. Make sure to import and add this to all of your pages:

Now our pages are more or less ready to be used for lazy loading, but we also need to remove all the imports we had with Ionic 2 to actually use the lazy loading.

3. Remove Page Imports & Change Usage

In all of your pages, you can now go ahead and remove the import statements for other pages.

Especiall go through the app.module.ts and remove the imports, remove the pages from declarations and also from entryComponents.

This looks kinda scary but helps to boost the performance and startup time of your app!

Now how do we actually use pages now?

Quite easy!

Every time we used the page name before, we now use the page name in ” so as a string. Ionic will internally hook up everything and find the right module for your page.

For example what was before:

Now becomes:

Every push, setRoot or create of a new page which looked before like:

Now simply becomes:

All of this can tike some time, but it’s worth it.

4. Add New Modules

A simple step, but needs to be mentioned:

We also need to import the BrowserModule into our app.module.ts. and if your App is using HTTP calls you also need to import the HttpModule like this:

5. What about Pipes?

Good question, and this one was quite hard on the first try. I’m not 100% sure it’s the best solution, but it’s the only one working for me right now.

For all the pipes inside your app create one file next to them called pipes.module.ts, which will declare and export all your pies like this:

You can now also remove all imports and usages of your pipes inside your app.module.ts, they will be imported when needed!

If you now want to use a pipe in one of your pages, you simply add the new Pipes module to your imports of that page like this:

This is a bit initial migration work, but hey you want that ionic lazy loading and the goal is near!

6. What about Components?

Custom components should be treated exactly like pipes. Just create a new components.modules.ts next to your custom components folder, declare and export what you got and when needed import like in the pipes example before.

Additional, you need to import the IonicModule here to use Ionic components inside that module, like here:

7. What about Providers?

All your providers will actually stay like they are. You don’t have to change anything here!

8. Having problems?

Sometimes you might encounter problems as pages are lazy loaded at later points and slow down your app at that time. In that case you might want to increase the priority for a page, check out the official documentation for setting the priority on how to set a higher priority for those pages (thanks to @BetaTools)!

Automate all the things!

Ok you might have noticed that a few steps above really need no brain, a monkey could do them as well.

I tried to outsource these steps into a little script, which will:

1. Add IonicPage import and decorator
2. Remove Page Import from other pages
3. Remove imports, declarations and entryComponents from app.module.ts
4. Create a NAME.module.ts for every page
5. Change the usage of Pages to passing a string instead of the class

Although this script saved me some time (after I worked on it for about half a day) it might not work for you, so make sure to have your source code under version control or somehow backed up. If this script fucks up your project it’s not my fault.

Anyway, if you have used and generated Ionic 2 pages with the CLI and never changed something the script should work for you.

Inside your Ionic 2 project create a folder upgrade-script and insert 2 files:

• page-template.ts
• page-upgrade.sh

The template will be used to create the new module files, insert this into the templates file:

Now the mighty script, insert this into the script file:

If you are a bash master and see improvements or want to change something, feel free to contact me!

Otherwise, I hope your upgrade to Ionic 3 lazy loading works fine with the above steps.

Yo can find a video version of this article below!