Upgrading 2.18.2 to 3.x

Hello everyone! :wave:

I’m starting the process of collecting resources to build a plan to finally upgrade an old (but new) Ember 2.18.2 app to… 3.x - haven’t decided if it should be 3.20 or 3.23.

Regardless, can folks point me to online resources covering this (arduous) task? I have already found the Upgrading topic on guides.emberjs.com.

Also, if folks have traveled down this path before, what should I be aware of?

Thank you for your time!

Searching for “upgrading ember app” yielded these promising posts:

1 Like

Those guides are probably great starts. Upgrading forwards-compatible packages as EmberMap suggests is a great thing to do early on. If you have a good test suite you will be in much better shape. That said you may have to begin to rewrite your tests using new-style tests which IIRC was introduced in 3.0(?).

My recommendation is always to step through versions a couple at a time. Big bang upgrades are always tempting but they can be way more work than incremental steps in the long run. IIRC the first few 3.x versions were more trouble than the rest. We recently upgraded our company’s main app and went from 3.0 => 3.1 => 3.2 => 3.4 => 3.8 => 3.20. The last jump was bigger and it still might have been smoother to take it by LTS releases (aka 3.12 and 3.16).

In general I usually do the following:

  • upgrade forwards compatible dependencies
  • run the ember upgrade to the target version with ember-cli-update
  • run the test suite, get it passing
  • address deprecations (or use ember-cli-deprecation-workflow)
  • repeat with next version

I’ve found that a lot of issues tend to be from addons, or have well documented workarounds or solutions if you search for the error. That said if you get stuck feel free to ask here! Lots of people going down the same path.

1 Like

Brilliant! :heart:

Thank you for the words of encouragement, and suggested path of upgrades.

Going from LTS to LTS is a good idea. So in your case, I’d aim to go directly from 2.18 to 3.4, and then each LTS after that.

The idea here is that actual breaking changes in public API should only happen at 3.0, and all the deprecations for those breaking changes should already be present in 2.18, so as long as you clear the deprecations first you should be safe on 3.0.

While there won’t be any intentional public API breaking changes in any of the 3.x series, apps (often via addons) frequently use some private API or rely on ambiguous behaviors that might change. When we know that’s likely, we make sure a deprecation message appears in an LTS before actually making the change, so stopping at each LTS gives you a chance to see those deprecations before they actually break.


Hi, I have an app developed in 2.16, few months back the ember cli is upgraded to 3.16. We updated only the packages and related configuration and made it worked. But my question is about octane, do we really need to upgrade it to octane, because we have around 25 journeys which is huge… Appreciate your advice

It depends what you mean by “upgrading to octane”. Octane is fully backward-compatible (which is why it’s all still in the Ember 3.x series).

If you mean rewriting all existing components to use @glimmer/component, no, you don’t need to do that. Similarly, if you mean rewriting all existing classes to change from .extend() to native classes, no, you don’t need to do that either.

But if you mean turning on all the octane feature flags so that your app is fully octane-enabled, yes, you should do that, and you should plan to write new code in the octane style, and consider refactoring bits of old code whenever you happen to be working on them.