Guide: How to update to Ionic 3.X


  • 08.11.2017 - Angular 5.0 and Ionic 3.9

I want to share this guide to the community because there comes often the question: “How can I update from Ionic 2.x to Ionic 3.0?”. This guide should help you to upgrade in just 3 simple steps.

Before you start there are three important points you should do first:

  1. Read the release blog post for Ionic 3.0 to understand which things have changed. Follow the links!

  2. Read the blog post about Ionic Native 3.

  3. Read the blog post about LTR support (shiped with Ionic 3.4).

Now we can start to update your Ionic 2.x App! There are only three simple steps you have to do.

Step 1 - Update your package.json

First of all, you should delete the node_modules directory. Then you can copy paste the required dependencies.

"dependencies": {
  "@angular/common": "5.0.3",
  "@angular/compiler": "5.0.3",
  "@angular/compiler-cli": "5.0.3",
  "@angular/core": "5.0.3",
  "@angular/forms": "5.0.3",
  "@angular/http": "5.0.3",
  "@angular/platform-browser": "5.0.3",
  "@angular/platform-browser-dynamic": "5.0.3",
  "@ionic-native/core": "^4.3.2",
  "@ionic-native/splash-screen": "^4.3.2",
  "@ionic-native/status-bar": "^4.3.2,
  "@ionic/storage": "2.1.3",
  "ionic-angular": "3.9.2",
  "ionicons": "3.0.0",
  "rxjs": "5.5.2",
  "sw-toolbox": "3.6.0",
  "zone.js": "0.8.18"
"devDependencies": {
  "@ionic/app-scripts": "3.1.7",
  "typescript": "~2.4.2"

Of course, you should keep your old additional dependencies if you added any other libraries. When you change your package.json you can run npm install.

Angular 5.0

Because of Angular 5.0 some Angular 4.x functions/objects etc. are deprecated. Follow this website to upgrade:

Step 2 - Update your app.module.ts:

Import the Angular BrowserModule in your app/app.module.ts file:

import { BrowserModule } from '@angular/platform-browser';

and then add it to the imports in the same file:

imports: [

If you are using Http, import the HttpClientModule in your app/app.module.ts file:

import { HttpClientModule } from '@angular/common/http';

and then add it to the imports in the same file:

imports: [
  HttpClientModule ,


Since ionic-app-scripts 2.0 you have to add the build/vendor.js file to your index.html.


  <!-- Ionic's root component and where the app will load -->

  <script src="cordova.js"></script>

  <!-- The polyfills js is generated during the build process -->
  <script src="build/polyfills.js"></script>

  <!-- all code from node_modules directory is here -->
  <script src="build/vendor.js"></script>

  <!-- The bundle js is generated during the build process -->
  <script src="build/main.js"></script>



Change <item-left> to <item-start> and <item-right> to <item-end>


Change <icon-left> to <icon-start> and <icon-right> to <icon-end>


Those of you who do not need to support RTL languages may be concerned by the CSS bundle size increasing. Don’t worry, we got you! By setting $app-direction: ltr in your Sass, your CSS will appear to be directionless (as if you never included RTL support in your app).

What if your app is RTL only? Same thing, just set $app-direction: rtl and your app will only support RTL.

Step 3 - Update to Ionic Native 3:

As you can see in the package.json we updated to @ionic-native/core and removed the old ionic-native dependency.

For each native plugin, there is now a new npm install command. For example, the Splash Screen can be installed with this command:

ionic cordova plugin add cordova-plugin-splashscreen
npm install --save @ionic-native/splash-screen

Go to the docs Native APIs - Build Open-Source Native Application Experiences and run the install command for all your used native plugins.

Then import your plugins in your app.module.ts file

import { StatusBar } from '@ionic-native/status-bar';
import { SplashScreen } from '@ionic-native/splash-screen';

and then add it to the providers in the same file:

providers: [
  { provide: ErrorHandler, useClass: IonicErrorHandler }

And change your app.component.ts imports from

import { StatusBar, Splashscreen } from 'ionic-native';


import { StatusBar } from '@ionic-native/status-bar';
import { SplashScreen } from '@ionic-native/splash-screen';

And that’s it! If nothing went wrong you should now run the latest Ionic 3.0 release. Run ionic serve to test it out.

Ionic 3 Lazy Loading

If you want to use lazy loading pages you should read the official upgrade guide.
I will update this part soon.

Follow Me.

Follow me on GitHub: danielsogl (Daniel Sogl) · GitHub


This is niche, but if you are using Angular animations, Angular 4 has decoupled the animations library from @angular/core, a bit like how Ionic changed Ionic Native. So if you move from Ionic framework 2 to 3, you might get an error like:

Please include either “BrowserAnimationsModule” or “NoopAnimationsModule” in your application.

The fix is to import BrowserAnimationsModule, and to change how the animations commands (trigger etc.) are imported. In app.module.ts:

import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
imports: [

and in the ts file where you are using animation, change where you import trigger, state, transition from:
import { trigger, state, transition, style, animate } from '@angular/animations';
not from @angular/core.


@LoLStats: Thanks for your guidelines. But I need to know is Ionic 3.0 stable yet ? I am also facing error in NavController modules after following your package.json. Whenever I am trying to navigate using navCtrl.push(SomePage) , it is showing errror argument type is not assignable to parameter type Page . My app is not tab based , previously i was doing routing with simple stack based navigation (push/pop pages) . Is there any conflict for Ionic-angular too?

thanks for this guide. But if you remove “ionic-native” you can’t use “ionic cloud” services anymore :frowning: :frowning: :frowning:

Huh? Where is which Ionic Service / Cloud Offering dependent on Ionic Native?

here :

Interesting, thanks!

I used the cloud service some weeks ago and had no problem with Ionic Native 3.0.
Looks like a newly made problem.

Upgraded as per instructions above but have these warnings that I don’t understand.

Any advice? Cheers.

npm WARN @angular/platform-server@4.0.2 requires a peer of @angular/animations@4.0.2 but none was installed.
npm WARN @angular/tsc-wrapped@4.0.2 requires a peer of typescript@^2.1.5 but none was installed.
npm WARN @ngtools/webpack@1.2.8 requires a peer of @angular/compiler@^2.3.1 but none was installed.
npm WARN @ngtools/webpack@1.2.8 requires a peer of @angular/compiler-cli@^2.3.1 but none was installed.
npm WARN @ngtools/webpack@1.2.8 requires a peer of @angular/core@^2.3.1 but none was installed.
npm WARN @ngtools/webpack@1.2.8 requires a peer of @angular/tsc-wrapped@^0.5.0 but none was installed.
npm WARN @ngtools/webpack@1.2.8 requires a peer of webpack@2.2.0 but none was installed.

Please can you confirm what the version should be? I get ionic 2.2.3 (as of #edballsday)

I see no 3.x or -beta?


2.2.3 is correct. It’s the latest stable version.

Version 3 (of the CLI) is currently in beta.

1 Like

Hi Ionic Team,
do you test your framework before releasing? I’m not able to create a simple application with an additional page - my own page.
I don’t care about the lazy loading stuff - just a simple page that I can navigate to.
If I try to add it to the main module, the compiler says that I need to decorate it with @Component, which of course I do.
I challenge you to create a simple app from scratch with your latest version of the framework and CLI and tell me if you suceeded.

If you’re just wanting to vent, then carry on.

If you want assistance, please post code and the exact error you are seeing, not a paraphrase.

Thanks for the guide!:slight_smile:

1 Like

I get this error when I try execute ionic run android: " error: cannot find symbol"
Tried to reinstall the android platform and the cordova-plugin-statusbar but it didn’t help.

I have Android SDK Build-tools V26 installed

This is me system information:
Cordova CLI: 6.5.0
Ionic CLI Version: 2.2.1
Ionic App Lib Version: 2.2.0
ios-deploy version: Not installed
ios-sim version: Not installed
OS: Windows 10
Node Version: v6.11.0
Xcode version: Not installed

This is my package.json:

	"name": "TMS",
	"author": "Adam Galmor",
	"homepage": "",
	"private": true,
	"scripts": {
		"clean": "ionic-app-scripts clean",
		"build": "ionic-app-scripts build",
		"ionic:build": "ionic-app-scripts build",
		"ionic:serve": "ionic-app-scripts serve"
	"dependencies": {
		"@angular/common": "4.1.3",
		"@angular/compiler": "4.1.3",
		"@angular/compiler-cli": "4.1.3",
		"@angular/core": "4.1.3",
		"@angular/forms": "4.1.3",
		"@angular/http": "4.1.3",
		"@angular/platform-browser": "4.1.3",
		"@angular/platform-browser-dynamic": "4.1.3",
		"@ionic-native/core": "^3.12.1",
		"@ionic-native/push": "^3.12.1",
		"@ionic-native/splash-screen": "^3.12.1",
		"@ionic-native/status-bar": "^3.12.1",
		"@ionic/storage": "2.0.1",
		"chart.js": "2.2.1",
		"cordova-plugin-ms-azure-mobile-apps": "^2.0.0-rc1",
		"ionic-angular": "3.4.2",
		"ionic-native": "^2.9.0",
		"ionicons": "3.0.0",
		"moment": "^2.15.1",
		"ng2-charts": "^1.4.0",
		"reflect-metadata": "^0.1.3",
		"rxjs": "5.4.0",
		"sw-toolbox": "3.6.0",
		"vis": "4.17.0",
		"zone.js": "0.8.12"
	"devDependencies": {
		"@ionic/app-scripts": "1.3.8",
		"typescript": "2.3.4"
	"description": "Time Management System",
	"cordovaPlugins": [
			"variables": {
				"SENDER_ID": "123123123123"
			"locator": "phonegap-plugin-push"
	"cordovaPlatforms": []

I had an old version of the cordova-plugin-statusbar (V2.2.0) on my config.xml, updating to V2.2.3:

removed my errors

1 Like

Little note: when i run ionic cordova build --release --prod i get a error:

Error: ./src/providers/googleAnalyticsProvider.ts
Module build failed: TypeError: Cannot read property 'content' of undefined
    at Object.optimizationLoader (/Users/marcel/Sites/projecten/tt/TimeTable/node_modules/@ionic/app-scripts/dist/webpack/optimization-loader-impl.js:14:24)
    at Object.loader (/Users/marcel/Sites/projecten/tt/TimeTable/node_modules/@ionic/app-scripts/dist/webpack/optimization-loader.js:5:32)
 @ ./src/app/app.component.ngfactory.js 24:0-65
 @ ./src/app/app.module.ngfactory.js
 @ ./src/app/main.ts

This is only with the --prod param
I needed to downgrade app-scripts to


Now the build is successful.

This looks more like a error in your code, you should open a new topic about that to see how you can get that fixed.

It’s already fixed, downgraded to app-scripts@1.3.4
But maybe it helps somebody with the same problem, thats why i posted it.

Downgrading is not a fix. It is a temporary workaround until other stuff breaks because of the old version of app-scripts. There always is a reason when a patch release gets released (as from .4 to current .8).