I’ve been using Ember.js for nearly two years now. Practically since 1.0 was released. That doesn’t make me smarter or more qualified, it just gives me a little more perspective [I like to think]. My current role is “Senior Front End Engineer” on an eleven person product team. That is to say, it’s my job to keep up with changes to Ember.js, help ensure best practices, file bugs, etc. I’ve also published and maintained a few add-ons. I’ve written this post in part to show you how I keep up with churn in the Ember community and in part to admit the pitfalls I’ve stumbled into along the way.

Depending on who you ask, upgrading packages in Ember-land is either one of its greatest stories or one of its biggest downfalls. Now, I’ll be one of the first to argue against the detractors that think Ember’s frequent deprecations and prompt release schedule are unsustainable for “real” development. The Ember community maintains a solid release momentum and determines necessary deprecations in order to bring about the ambitious features of a modern framework while simultaneously simplifying best practices and eliminating chaff. In fact, the “train model” Ember follows for its releases is the same concept that TC39 is using for the JavaScript language spec moving forward; work is already continuing on future releases before the next version has landed. To me, that’s a really powerful strategy that shows a commitment to moving forward and continually improving the framework instead of getting left in the dust as so many major projects have experienced throughout the evolution of the web.

However, this doesn’t mean that upgrading your application is all butterflies and unicorns. Depending on the complexity of the code, what era of Ember it started in, and a number of other factors, it can seem a daunting task to keep your project up to date.

The Happy Path

All that being said, a happy path does exist for Ember upgrades, and it’s a good one. If your app has followed Ember best practices and not used private library internals, you should be able to upgrade from one version of Ember to the next without much issue. Let’s say you have an app on Ember 1.10 and the latest version is 1.12. The upgrade process looks something like this:

1. Upgrade Ember-CLI to v0.2.3
2. Run `ember init` and say yes to all prompts (you can say no if you know you don’t need a change, of course, but I find Step 3 to be easier)
3. Diff the changes Ember-CLI has made to your app and revert any that you don’t need (such as README, index.hbs, overwritten configs etc)
4. Test your app to make sure it isn’t broken with the newest versions
5. Assuming all is well, repeat steps 1-4 with Ember-CLI v0.2.7

Shazam! Your application has been upgraded to Ember 1.12. Even better, starting with 1.13.x and moving into the 2.x series, the versions for core libraries such as Ember-CLI, Ember-Data and others have been synchronized with the core Ember release. This means that if you want to upgrade to Ember 2.1, for example, you can use Ember-CLI 2.1′s `ember init` command. More information on this standardization can be found on the Ember blog.

Note: Each Ember-CLI Release explains how to upgrade the package, but I have two npm scripts that make it even easier:

“scripts”: {
  “postinstall”: “bower cache clean && bower install”,
  “clean”: “npm cache clean && bower cache clean && rm -rf node_modules bower_components dist tmp”
},

With the above, my upgrade command looks like this:

npm uninstall -g ember-cli && npm run clean && npm install –save-dev ember-cli@x.y.z && npm install

Keep in mind that you don’t want to add that postinstall script to an addon, just an application that won’t be consumed by another project via npm.

Now, some of you might be sitting there shaking your heads; there’s no way it can be that easy, right? Well, as all things in the software world, YMMV and there are always exceptions. That said, in many cases pre-Ember 2.0, you shouldn’t need much more than that. Things get a little murkier with the story surrounding other libraries tangential to core Ember, but that process is improving as well.

For those of you that are pioneers in the community, the above path may not exactly work for you. New Ember versions generally land before the accompanying Ember-CLI release, so if your team is dedicated to staying on the bleeding edge of framework changes, you may not always be able to leverage Ember-CLI for every upgrade. Additionally, dependencies that release new versions after Ember-CLI gets updated won’t be included in the `ember init` command. That’s why I heavily utilize VersionEye to track my projects’ dependencies and get notified of repo updates as they are released.

Pro Tip: Once activating VersionEye for a branch’s package.json and bower.json, you can open the bower “project” settings and merge it into the package.json “project”, giving you a combined view of both sets of dependencies in a single easily accessed page.

That said, those of us who undertake the role of a pioneer should expect to encounter more churn and issues up-front. It’s people like us whose job it is to discover problems as quickly as possible, so that when people use the Happy Path described above, they can upgrade relatively effortlessly. Besides, if you’re moving on to new versions faster than Ember-CLI can update to support it, you probably know all about new best practices and deprecations before the rest of the community anyway, right?

Check out Part II of this series for what to do when the Happy Path just won’t cut it. Then, learn about dealing with deprecations in the finale, Part III.

Special thanks to Thomas (@djvoa12), Spencer (@spencer516), and Ben (@bdvholmes) for reviewing this series!