Upgrade to Ionic 3 Lazy Loading (With Script!)

upgrade-ionic-lazy-loading-header

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.

The Ionic Academy

More content, more detailed video courses and community help inside the member area.

Not an Ionic Academy Member? Click here to learn more

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.
ionic-2-folder-structure

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 theionic-2-pipes-structure 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!


Get the free 7 day Ionic Crash Course to learn how to:

  • Get started with Ionic
  • Build a Tab Bar navigation
  • Make HTTP calls to a REST API
  • Store Data inside your app
  • Use Cordova plugins
  • Style your Ionic app

The course is free, so there's nothing you can lose!

Powered by ConvertKit
  • AJ Barry

    I just finished migrating my app to Ionic 3.0.1 but I was stuck figuring out how to get my custom pipe to work. This saved me so much work, thank you!

  • I’d really enjoy learning about some of the benefits people have had before pursuing this change myself. How much faster did their app appear? Was startup time improved significantly? What are the drawbacks, if any? Can this be mixed? Do we have to convert all our pages – or can some be changed and others left to load resources the old way?

    • Jeffrey Chen

      Agree with this reply. I would like to know why we spent time doing these changes, too.
      The cost is high when our app gets bigger and these updates always takes a lot of time checking if everything is still working.

  • Pingback: Simple Ionic 2 Login with Angular 2 - Devdactic()

  • BetaTools

    Why do you import BrowserModule into the module.ts files? Is it necessary?

    [EDIT]
    I misunderstood. I can see its imported into app.module.ts. At first I thought you imported it into all module.ts files 🙂

    • Yeah it’s only imported once, but it’s needed there since Ionic 3 🙂

      • BetaTools

        Thanks for a nice tutorial btw. I’m currently transforming my app to use lazy loaded components. I had one minor issue though that some components were a bit slow when I needed them. Just found the documentation for preloading components. Maybe you could add it to your guide if it fits the purpose. http://ionicframework.com/docs/api/navigation/IonicPage/ Look at the bottom where it says “Priority” 🙂

  • Pingback: Building Your Own Ionic Wordpress Client with WP-API - Devdactic()

  • Neo Split

    Thanks for the tutorial. BTW the error you get at timestamp 12:00 in video (ioncardheader unknown) is because you in your components.module.ts file, you need to “import” IonicModule, so your custom components know of Ionic Components.

  • Tobias Mücksch

    I’m having issues using custom components like it’s described here. I’ve opened an issue:

    https://github.com/driftyco/ionic/issues/11560

  • Christian Neil Anthony Wico

    Dat script “exclude” variable, tho’… 😉

    • I’m not really a scripting hero, I can sometimes bend it to my needs but it’s by no means good 😀

  • Justas Kuizinas

    I am getting error sed: can’t read s/@Component/@IonicPage()@Component/g anyone solved this?