Everything you need to know to upgrade your Ember.js app (including Ember 3)
This post will be a roundup of the most important resources know about, whether you’re upgrading minor versions or making the jump from Ember 2 to Ember 3, which was released in January 2018.
Ember has some amazing, first class tooling and process to make upgrading as easy as possible. I hope your experience is as good as mine! I’d like to thank everyone who works to make that possible.
If you skim the article, it might look like there’s a lot to know, but chances are you’ll only need a small piece of it! My goals is to give the lay of the land and help you know what to expect from the process.
This article was written as of Ember.js 3.1.
Quick reference
I’ll go into some things in more detail later, but in brief:
- Follow the ember-cli release notes to update your command line installation of the ember-cli. It’s basically
npm install -g ember-cli@x.y.zwhere x.y.z is the version like 3.1.0. (Did you know you can use the latest version of the cli even when working with older apps?) - Read the Release Blog Posts for Ember.js to get the big picture, learn about new features, and get insights into upcoming changes
- Use the ember-cli-update tool to actually do the upgrade. Read the REAME from top to bottom before you start. This tool will update a bunch of dependencies in package.json that are meant to work together, plus it has options to run codemods that do the syntax changes for you, if there are any available for the version you’re moving to. See more advice in “What to expect during upgrading” below, especially if you’re going from Ember 2 to 3.
- Resolve deprecation warnings you see in the console. This is required for major version upgrades (2.18 to 3.x), and advisable for minor upgrades. A full list of deprecations and how to fix them can be found here.
- Consider upgrading to the latest test helpers too
What to expect during upgrading
There’s more to upgrading a front end framework app than just changing a line in your package.json! The number one mistake developers make in their first upgrade is to assume that it’s like updating dependencies like moment or d3.
In order to make upgrading easier, Ember.js has a somewhat unique approach to deprecations and new features, compared to other frameworks. Changes in minor versions (like 3.1 to 3.2) are for adding new features and bugfixes, while major version jumps (like 2.x to 3.x) are when deprecations are removed and no new features are added. This approach helps prevent churn in your app and your experience with the API.
Minor version upgrades
If you are upgrading a minor version, say from 3.1 to 3.2, most of the time you should just be able to update a few things in your package.json and carry on. For projects like Ember that follow semver, minor versions are for non-breaking changes, like adding a new method or options. Things that can affect your ability to easily update are using private API methods or unmaintained addons. As you move through minor versions, new deprecation warnings will show up in the console and your tests. It’s a good idea to resolve them as they arise, so that later version jumps are easier, smaller PRs.
Major version upgrades
If you’re doing a major version jump, you have to keep in mind that deprecations are removed in the major version. So, your upgrade path is to get to the final minor version of the series first, fix all the deprecation warnings that show up in the console/tests, and then upgrade the major version. If you’re going from Ember 2 to 3, I advise upgrading to 2.18, make sure it works, run the ember-cli-update codemods, resolve any outstanding deprecations, and only then jump to 3.x. It can take time to make the changes in your codebase, but the codemods tooling will help a ton.
My experience
In my case, it took 2 engineers one full day to go from 2.12 to 3.0. What slowed us down the most were things we did to ourselves — one mistake reviewing the upgrade diff, someone renamed our app badly in the past, and there was a really bizarre template typo that I’m surprised ever worked. Our app is small and sticks really closely to the “happy path” of Ember (no weird workarounds, no using private API, only using very popular addons) so I can’t say what the norm is, but I’m really happy.
If you get stuck or confused…
As you resolve the changes suggested by the ember-cli-update tool, take a look at the ember-cli’s app blueprints if you are confused about what to keep. Click on the ember-cli release tag name for the version you want, then blueprints/app/files and you can see what all the boilerplate should be. Here’s an example.
The ember-new-output app is helpful for seeing what changed in the blueprints between versions (thanks Alex Middeleer for the tip).
I also found it helpful to look at the Super Rentals app, which is kept fairly up to date. That way I could see examples of working routes, tests, etc. and compare them to my app. Super Rentals is part of an official Ember tutorial.
Of course, there’s always Googling. But if you need another pair of eyes, there are multiple places to ask for help, like chat, Stack Overflow, and the Forums. I had to ask for help when I was tracking down the weird bug related to my app name. Ricardo Mendes aka locks is super awesome, and he saved me hours of debugging by pointing me towards the right files to look at.
When should you upgrade your app?
The answer varies by your development cycle, but if you aren’t going to be updating frequently, it’s a good idea to at least follow the LTS (Long Term Support) releases. LTS versions are those which receive bugfixes and security updates for a longer period. They are usually every 4 versions plus the final version of major releases. So, that will be 2.12, 2.16, 2.18, 3.0, 3.4, etc.
Sometimes, the answer of when to upgrade is driven by new features. Reading the Ember.js Times and the Release Blog Posts are good ways to know when new features are in development. It’s nice to not be caught off guard by changes. The Times is also good for keeping track of new RFCs (Request for Comments) so that you have a chance to give your input on upcoming features and deprecations.
What about tests?
When you go from 2.18 to 3.0, if you use ember-cli-update’s codemods, it will change your tests a lot in order to make them use the new ember-test-helpers. However, I learned from Tobias Bieniek that the changes are optional — I didn’t actually need to change my tests for 3.0. However, there are some much better options for handling async in tests, so I highly recommend it!
One gotcha is that if you’re used to looking at the Ember API docs for documentation of testing helpers, you need to be looking at the ember-test-helpers documentation page instead now. (This is not ideal and the docs should be rolled into the main website. If you can to help, drop by the #dev-ember-learning channel on the Ember Discord).
Check out Tobias’ EmberConf talk, The Next Generation of Testing, for a walkthrough of the features available and what’s different:
Another library that may help make your test migrations go more smoothly is qunit-dom, if you have been using removed methods like findWithAssert . Thanks to Ben Demboski for the tip.
Community Tutorials
There are a bunch of community articles that give more step-by-step instructions too! The ember-cli-update tool is fairly recent, so watch out if you’re looking at tutorials in 2017 or earlier, because you might be missing out on some good stuff that makes the process easier.
I really appreciated How to upgrade Ember.js to 3.x and live to fight another day by Nicolas Torres Gussoni. It has a different approach than I’ve outlined, but covers some pieces in more detail than I have here.
Did I miss something?
Do you have some hard-won advice to share? Did you try to upgrade and run into problems that could have been prevented with better learning materials? Please comment and let me know.
Thanks for reading :)
Jen Weber builds apps for science at BioBright. She’s a contributor to Ember.js, an open source, front-end framework that provides shared solutions for tough problems, where development is guided by the community rather than any one company. She works to transform tech into an industry that welcomes new people.
