I’m currently working on upgrading an Ember 1.9.1 application to the latest Ember version. I understand that a direct upgrade may not be straightforward due to the significant framework changes over the years.
Is there an officially recommended path or tool to help migrate from Ember 1.x to the latest version? If so, what are the key steps I should follow to ensure a smooth transition?
Any guidance, best practices, or shared experiences would be greatly appreciated.
Wow that will be a wild ride. Feel free to live blog your progress
I wouldn’t say a big bang to 6.3 would be technically impossible, but it would be practically impossible. We’re talking 11 years of framework, ecosystem and language differences.
Hopefully the app is in “good shape” for upgrade. What that means to me:
adherence to the “happy paths” of Ember and not too much crazy stuff
limited reliance on dead addons, limited 3rd party lib/addon usage in general
good test coverage to catch regressions
no “extras”: nothing wrong with using FastBoot or Engines but it could make things a little more complex when upgrading
obviously the general size of the app is relevant too
Now in terms of overall strategy… this is going to be a mix of hazy memories and recent experience so take it with a grain of salt but I’ve traversed from early 1.x to 4.x (and 4.x to 6.x separately) so I have some experience here. For Ember 3.x onward I’d recommend bumping from one LTS release to the next and running the blueprint updates along the way.
General advice:
Use ember-cli-update as soon as you can. I don’t remember how far back it goes in terms of compatibility, so you may have to do things manually until the 2.x range(?)
Take it slow: for Ember 3.x onward I’d recommend bumping from one LTS release to the next and running the blueprint updates along the way. You could probably do 2-3 LTS versions at a time if you wanted but that could get overwhelming. I like to break things into small chunks.
Try to minimize your addons footprint, and update your addons as aggressively as you can during the upgrade. Figuring out which addon versions are compatible can be tricky but I find this to be the biggest source of pain during upgrades.
Use the codemods and lint autofixers when you can. Some of them work better than others but it’s a great way to automate some really tedious work.
1.x => 2.x
This will probably be the most difficult stage. IIRC there was a lot of churn in the 1.11=>1.13 range and that was pretty rough. Also relevant documentation is harder to find and managing node versions and old dependencies might be a bit of a challenge too. In general the hardest part of updating is keeping all your addons at the right compatible version range.
2.x => 3.x
I remember this being a mixed bag in terms of deprecations but not too terrible. Ember 2.4 was the first LTS release so from there I’d start jumping LTS releases. Make sure you read the release notes carefully. You could try ember-cli-update but I’m not sure if it will work this far back.
One thing that did happen in this range is dropping bower. Mostly that should be a straightforward system of moving packages to package.json and I don’t think we ran across any that were particularly difficult, but depending on how big your bower file is this could be a chore.
3.x => 4.x
There are a TON of deprecations introduced in 3.x. It was a super long major version cycle. This is where I’d highly recommend taking 1 LTS at a time, resolving all deprecations, and moving to the next one. If you want until the 3.28 point like we did it will seem really overwhelming. This is also where the tooling got a lot better though so you can use ember-cli-update, the lint fixers and codemods to help you out.
4.x => 5.x
This is only 12 minor versions long and far fewer deprecations. It’s mostly smooth sailing however Ember Data went through a lot of changes here so depending on how heavily you use Ember Data this may affect you a lot.
and…
I can’t think of a whole lot else to mention at this point but will let you know if I do. Feel free to come back here or ask in Discord if you get stuck, although finding people who remember the 1.x days well enough might be a challenge. Best of luck!
The other option, of course, would be to rewrite the app starting with modern. I wouldn’t normally recommend that but depending on the size of your app it might actually take less time and be more enjoyable if you have to migrate that far… That’s a much tougher call.
Traditionally, I think that for most cases the recommendation would be to go 1 major version at a time, using as many of the built-in tools as you can.
However, this largely depends on the size of your app and how much your current version follows convention. Having done this many times, and in the process of actually upgrading from 1 → 6 again, I personally at this point take a very different approach to it… But my approach requires a very seasoned understanding of the builds, app structure etc.
In your shoes, no matter the size of the app, I create my Vanilla Ember 6 application, setup a “shell” if you will, for the structure of my app logic, and then programmatically migrate all of your routes/controllers/components/services automatically:
Creating the module via blueprint “ember g bla”
Moving the logic from old file, to new file
Using both community jscodeshfit transforms, and custom transforms to convert the logic over.
Disclaimer, this approach is not straight forward as I’m probably making it sound and success / timeframe is heavily dependent on skill level, as there will be learning curves to write custom transforms, using these tools, etc. Being a git expert and incorporating git commands into the automation helps tremendously. The big “pros” to the approach is that if your old/current app continues to go through changes, that doesn’t need to stop, so no “code freeze” required, and you get to clean up any unused logic for free.
One caveat to this: you can save yourself a little grief if you skip the major version itself and go straight to the next LTS. For example I went from 3.28 => 4.0 and ran into a bunch of bugs that had been fixed in 4.4 so it was actually easier to go from 3.28 => 4.4 than to 4.0
