The Meteor 1.2 Upgrade Experience

Migrating to Meteor 1.2

So you’ve heard about Meteor 1.2, MDG’s biggest release since 0.9, and you want to know what it’s like to try it out, eh? Look no further, this guide will show you how to actually change your apps to try out 1.2, even before it’s fully released.

A word of caution: to run a pre-release version of Meteor the workflow is a little bit different, so I’ll help you through some potential pitfalls.

The Meteor 1.2 Experience

In this Meteor Forum Post announcing 1.2, MDG outlines these points about Meteor 1.2:

  • Faster application rebuild times, thanks to a new plugin architecture
  • Built-in support for ES6/ES2015 JavaScript features
  • Cross-package LESS and Stylus imports
  • Upgrades to Cordova mobile support
  • Official support for React and Angular as view layer alternatives to Blaze

So, how do you get started taking advantage of this new power of expressiveness?

The Upgrade Process

There are two components to running Meteor - the packages that make up your application, and the command line tool meteor you use to start up the Node and Mongo processes. For a smooth experience running pre-release software, it’s best to have a development version of the command-line tool on your system.

But first, the easy part, let’s get the newest packages in your app.

Upgrading packages

Change directory to the app you wish to upgrade and run one of the following, to update to the release candidate as of this article, or to the latest one, including the released version if it’s been released:

> meteor update --release METEOR@1.2-rc.12
# OR
> meteor update --release $(curl -sL | sh) # the latest RC, or 1.2 if it's out

This will download new packages for that release, and update your app’s packages and versions files.

Here’s a diff of the packages file, showing how the major umbrella package meteor-platform has been replaced by sub-components. This is good to the extent that - if you don’t need one of these components - you can take them out and save on the size of built JS that is pushed out to your Web and Mobile clients.


@@ -24,3 +23,17


Pro tip: Make a commit after running this update, and immediately after do a meteor add ecmascript, and commit that as well. More on this later in the ES6 section.

At this point if you run your app the usual way, it’s possible you *may* get strange errors. If not, great! But since this happens to quite a few people, here’s how to keep everything working together.

Using the pre-release command-line tool

In a nutshell, you simply need to checkout the Meteor GitHub repo, change to its release-1.2 branch, and point to the meteor executable in its root.

> cd ~/src
> git clone
> cd meteor; git checkout release-1.2
> alias meteor-devel="~/src/meteor/meteor"

Now you can use meteor-devel to run your app, should any problems arise with meteor tool. When you run it you’ll see:

meteor-devel --port 4160
=> Running Meteor from a checkout -- overrides project version (Meteor 1.2-rc.12)

Observable Changes ?

You’ll see in any JS console that Meteor.release shows the current version. I often do this on sites I visit to see what release they are using.

Also, build times are faster. I found it difficult to measure how much faster, but 1.2 is rebuilding only changed files during each development build, so on large codebases there will be a noticalbe difference.

I saw little-to-no difference in built JavaScript size, but you’ll want to measure this for yourself before deploying to production, as it depends on what packages you include.

For example, if you don’t need blaze-html-templates, and get rid of it, you can save 18k right there! So the modularity ought to lead to smaller file sizes, if you take care to only include what you need.

ES6 aka ES2015

This is the biggest developer-affecting change in Meteor 1.2.

If you’ve never used ES6, you can start right away in Meteor 1.2, without renaming files to *.es6.js or any such shenanigans. Feel the power of writing JS in fewer characters, and without needing utility libraries for nearly everything.

  // old
  var double = function (x) { return x*2; }
  // new !
  let double = (x) => x*2

  //old[1,2,3], double)
  //new !

There are many more examples of real world ES6 for Meteor.

Just be sure to immediately do a meteor add ecmascript upon migrating to 1.2. While ecmascript may be present in your .meteor/versions file as of the upgrade, Meteor will not process your ES6 JS files unless it is also listed directly in your .meteor/packages file. This may lead ot hard-to-diagnose errors, as client-side ES6 files work fine in your ES6-enabled browser, but server-side files fail with syntax errors.

Incidentally, if you want to be able to use cool features like arrow-functions directly in your browser console (and who doesn’t!), here’s showing how to launch Chrome with the --harmony flag:

Arrow Functions

Because ES6 Arrow functions limit the dynamic this feature of JavaScript, you should not use them for places in Meteor where you require this. A partial list of these are:

  • Publish functions: this.userId
  • Meteor methods: this.unblock
  • Template callbacks: this.autorun


As I have mentioned before, Promises, one of neatest features of ES6, allow you to clean up callback-accepting functions. HTML5Rocks breaks it down even further. If you meteor add promise, you can now get an MDG-maintaned Promise polyfill that lets you do async in a much cleaner fashion than before.


async1().then(async2).then(async3).catch(/* err */)

If you also use the okgrow:promise package, you’ll have access to Promise-based versions of Meteor method calls, HTTP methods, and a way to turn any callback-accepting function into a Promise-returning one, much like Meteor.wrapAsync does with Fibers.

This package has been tested to work with Meteor 1.2 already, and will help you write cleaner and more idiomatic ES6. (disclaimer: OK GROW! authored this package, so of course we love it)

Not all ES2015 features enabled

All things ES6 will not work right away in Meteor 1.2. ES6 modules are not supported just yet until MDG figures out how to replace the existing namespacing in Meteor with them.

To see which features are supported, this build file lists the ones that are currently active, and the test suite for the ecmascript package also shows what features you can count on.

The explanation for gradual rollout that I’ve heard is that MDG wants to enable a subset of features that are least likely to change for the future.

In the meantime, if you need things like async/await, or experimental features, you can use the deprecated, but still working grigio:babel, which whitelists more transpilation features. And for using ES2015 modules today, you can try a package called universe:modules.

Already Meteor is the best place to write ES6 code with the widest reach and least worry, so I think it’s worth sticking to the parts they’ve deemed safest to implement for now.

Pluggable Views: React, Angular

Migrating an application to React or Angular from Blaze, Meteor’s built-in templating system is not going to be automatic of course. But with 1.2, MDG is officially showing that Meteor is more than just Blaze, by letting you remove blaze and use React or Angular instead.

Check out the Leaderboard example in Angular or React, if you think a move to one of these popular architectures may be for you. Then feel the satisfaction when you meteor remove blaze-templates and use the front-end of your choosing!

That said, Blaze has a great deal of new improvements, detailed in the official Meteor Upgrade Guide, including Spacebars subexpressions for combining helpers, and more powerful name scoping.

Cordova Support

The Meteor Upgrade Guide outlines these points:

  • Cordova has been updated to 5.2.0.
  • To use the vastly improved WebView for older Android versions, Crosswalk, simply meteor add crosswalk
  • The bundled Android tools have been removed and a system-wide install of the Android SDK is now required. This should make it easier to keep the development toolchain up to date.

More to Come

So far there’s no evidence that MDG will be moving routing or Velocity into core, or a SQL database as a Mongo alternative. But with the release date estimated to be mid-October, it’s worth staying tuned to MDG and this blog, where we’ll keep you posted on what’s changed.

This is a very developer-centric set of changes. None of these changes will out-of-the-box directly affect end-users’ experience, but to the extent that they let developers iterate quicker they are certainly nice to have! Also, ES6 changes alone could result in massive changes to how we write and execute JavaScript. Maybe that’s enough to focus on in one major release.

Good luck with your upgrades!

Further Reading

Let's stay connected. Join our monthly newsletter to receive updates on events, training, and helpful articles from our team.