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.

Updating

As usual, you can update your Meteor install with:

 meteor update

Auto-update

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 .meteor/packages.

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 .meteor directory.

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.

Migrating

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:

mrt migrate-app

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.

Name Changes

Starting from 0.9.0 forward, packages must reference their author’s name (so kadira becomes meteorhacks:kadira).

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 cmather:iron-router.

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):

  • iron:router
  • iron:layout
  • meteorhacks:npm
  • meteorhacks:kadira
  • meteorhacks:fast-render
  • meteorhacks:subs-manager

The Return Of mrt

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).

Cleaning Up

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 *.meteor.com

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.

This way, you’ll only need to repeat this whole process when that module changes, instead of whenever your package changes. For example, here’s a simple wrapper I created for the Juice module.

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:

  1. Create a new 64-bit Linux Digital Ocean box (or EC2, Linode, etc.) and ssh into it.
  2. Install Meteor with curl https://install.meteor.com/ | sh.
  3. Log in into your Meteor Developer account with meteor login.
  4. Install the necessary utilites: sudo apt-get update; sudo apt-get install build-essential
  5. Run meteor publish-for-arch authornNme:packageName@version. In my case, meteor publish-for-arch sacha:juice@0.1.0.

See this thread for more information.

Other Resources