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.
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:
- Create a new 64-bit Linux Digital Ocean box (or EC2, Linode, etc.) and
ssh
into it. - Install Meteor with
curl https://install.meteor.com/ | sh
. - Log in into your Meteor Developer account with
meteor login
. - Install the necessary utilites:
sudo apt-get update; sudo apt-get install build-essential
- 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
- 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.
Comments
comments powered by Disqus