Updating to 0.9.0: What You Need to Know
Meteor’s 0.9.0 update introduced a brand new (and long awaited) official package manager.
The good news is that going forward, dealing with packages will be a lot easier. The less-good news is that updating your app to the latest version might be a little trickier than usual.
As usual, you can update your Meteor install with:
When you run
meteor for the first time after 0.9.0, you may notice that it says something about “auto-updating to 0.9.0 and removing old versions”.
Don’t panic! This won’t actually auto-update your app. Once it’s done downloading 0.9.0, it’ll re-download the version of Meteor (such as 0.8.3) that you need to run your app.
If you happened to stop the process midway through (perhaps by pressing control-c), you may have gotten your
~/.meteor into a broken state. If that’s the case, just remove that directory, and re-install Meteor with
curl https://install.meteor.com/ | sh
The Good Old Days
To understand the issues you’ll potentially run into during the update process, let’s take a look at how packages used to work. Before 0.9.0, Meteor didn’t have its own package manager, but it could pick up on local packages installed in the
/packages directory provided you added their name to
So it was Meteorite’s job to fetch packages from Atmosphere, install them in
/packages, and then tell Meteor about them by adding their name to the list. As far as Meteor was concerned, you had coded all these packages yourself.
Bye Bye Meteorite?
But now that Meteor can take care of this whole process by itself, it knows the difference between an Atmosphere package and a local, app-specific package. So from now on, app-specific packages will live in the
/packages directory as before, but Atmosphere packages will live somewhere in the nethers of the
There’s just two caveats though. First, some Atmosphere packages haven’t migrated to the new package format yet, and as such Meteor doesn’t know what to do with them. For these, you’ll need to hang on to Meteorite just a little longer.
Additionally, if you want to load a package directly from a Git repository (i.e. it’s neither available locally or hosted on Atmosphere), you’ll also need to use Meteorite for now.
First, make sure you have the latest version of Meteorite:
npm install -g meteorite
You can then migrate your app to 0.9.0 using the following command:
What that command is trying to do is go through your
smart.json file, look at each Atmosphere package you’re currently using, and add that package to
.meteor/packages using the new naming format.
It probably won’t work out of the box though. Read on to understand why.
Starting from 0.9.0 forward, packages must reference their author’s name (so
When Atmosphere migrated to the new system, the migration automatically tried to pick up the package author’s name according to their Meteor Developper account.
So for example,
iron-router was originally authored by Chris Mather and published to Atmosphere using his
cmather Meteor Developer account, so it got migrated as
There’s just one issue: some authors decided to republish their packages under different author names. So the updated version of
iron-router is actually accessible as
iron:router (“the router package by author iron“).
This means that in some cases,
mrt migrate-app will try to install the wrong, unupdated package, and you’ll have to instead manually edit
.meteor/packages with the correct package name.
To get you started, here’s a list of the new names of commonly used packages (you’ll have to search Atmosphere for the rest):
The Return Of
And what if a package isn’t linked to a Meteor Developer account at all? In that case, Atmosphere defaults to using “mrt” as an author name (for example: mrt:moment).
If this happened to one of your packages, you can go claim it (but don’t worry,
mrt:packageName will still work even after you do).
There’s a few places you might want to double check after you’re done updating.
/.meteor/packages: This should be automatically updated for you, but it’s good practice to take a look and make sure everything is in order. I also suggest grouping packages into Meteor packages, Atmosphere packages, Unmigrated Atmosphere packages, and local packages.
/packages/: You can safely remove any package symlinks (or aliases, is you’re on Mac OS) in here since Meteor is now taking care of those, except unmigrated packages (see caveat above).
/smart.json: You should remove everything from there except unmigrated packages.
/packages/.gitignore: No need to ignore all that stuff anymore. You can remove everything from there except unmigrated packages.
A Note About NPM
If you’re using NPM packages with binary dependencies inside your app, be aware that the 0.9.0 update can make it harder to deploy on
If that’s the case, you’ll need to publish the package for the server’s specific architecture, in this case 64-bit Linux.
Assuming you’re developing in another environment, here’s what I suggest. First, it might be a good idea to break off the NPM modules you’re using into their own, dedicated packages.
Create your package, then publish it to Atmosphere with
meteor publish --create.
Once that’s done, you can get to work on actually publishing your new package for the target architecture:
- Create a new 64-bit Linux Digital Ocean box (or EC2, Linode, etc.) and
- Install Meteor with
curl https://install.meteor.com/ | sh.
- Log in into your Meteor Developer account with
- Install the necessary utilites:
sudo apt-get update; sudo apt-get install build-essential
meteor publish-for-arch authornNme:packageName@version. In my case,
meteor publish-for-arch sacha:email@example.com.
- Introducing Meteor 0.9.0 and the official Meteor packaging system: the original announcement post.
- Migrating Apps: official guide.
- Migrating Packages: official guide.
- Build your own Meteor package for 0.9.0 +: a detailed walkthrough about creating your own package.
- Add Meteor 0.9 support for your Existing Packages: a quick guide about migrating your existing packages.
- Isobuild: why Meteor created a new package system: more info about the logic behind the new package system.
- Unipackage: everything you need to know about the new packaging server.