Foo Hack

npm is a NodeJS package manager. As its name would imply, you can use it to install node programs. Also, if you use it in development, it makes it easier to specify and link dependencies.

Installing npm

First of all, install NodeJS. Like so much of the NodeJS ecosystem, npm is very young, so you’ll generally have to use a very recent version of node in order to use it. At the time of writing this, that means at least version 0.1.103.

To install npm in one command, you can do this:

curl npmjs.org/install.sh | sh

Of course, if you’re more paranoid than lazy, you can also get the latest code, check it all out, and when you’re happy there’s nothing in there to pwn your machine, issue a make install or make dev.

what, no sudo?

I strongly encourage you not to do package management with sudo! Packages can run arbitrary scripts, which makes sudoing a package manager command as safe as a chainsaw haircut. Sure, it’s fast and definitely going to cut through any obstacles, but you might actually want that obstacle to stay there.

I recommend doing this once instead:

sudo chown -R $USER /usr/local

That sets your user account as the owner of the /usr/local directory, so that you can just issue normal commands in there. Then you won’t ever have to use sudo when you install node or issue npm commands.

It’s much better this way. /usr/local is supposed to be the stuff you installed, after all.

Getting help: npm help

npm has a lot of help documentation about all of its commands. The npm help command is your best friend. You can also tack --help onto any npm command to get help on that one command.

Installing stuff: npm install

You probably got npm because you want to install stuff. That’s what package managers do, they install stuff.

npm install blerg installs the latest version of blerg. You can also give install a tarball, a folder, or a url to a tarball. If you run npm install without any arguments, it tries to install the current folder.

This command can do a lot of stuff. npm help install will tell you more than you ever wanted to know about it.

Showing things: npm ls

The npm ls command shows what’s on your system, and also what’s available in the registry. The arguments are beautifully colored greps. For instance npm ls installed would show you what’s installed on your system. npm ls installed marak would show you all the packages installed on your system created by Marak.

npm help ls for more info.

Updating packages: npm update

The update command does a few things.

1. Search the registry for new versions of all the packages installed.
2. If there’s a newer version, then install it.
3. Point dependent packages at the new version, if it satisfies their dependency.
4. Remove the old versions, if no other package names them as a dependency.

So basically, update behaves a lot like a “standard” package manager’s update command, except that it also checks to make sure that the new version isn’t going to break anything before it points stuff at it.

You see, npm keeps you out of dependency hell.

Development: npm link

The link command symlinks a package folder into your system, so that changes are automatically reflected. It also installs the "dependencies" and "devDependencies" packages from your package.json file.

This is one of the most useful tools for developing programs with node. Give your thing a name and a version in a package.json file. Specify a few dependencies and a main module. Then run npm link, and go to town coding it and testing it out in the node repl. It’s great.

npm is a development tool, first and foremost. People sometimes say “Yeah, I haven’t gotten time to check out that package manager stuff yet. Maybe I will when my code is more stable.”

That’s like saying that you’re going to start using source control when your code is done. It’s just silly. Source control should make your process easier, and if it doesn’t, then you’re using a broken SCM. Same for package management. It should make it easier, and if it doesn’t, then something is wrong.

npm isn’t “for” publishing. That’s just something it can do. It’s “for” playing. That’s why I wrote it: to play with your code, without having to remember a dozen different ways to install your stuff, or having to get you all to structure your code the same way.

It’s supposed to make the process funner.

Making a Package: The package.json file.

The package.json file goes in the root of your package. It tells npm how your package is structured, and what to do to install it.

Most of the time, you only need the "name", "version", and "main" fields (even for node-waf compiled addons).

If you don’t know json, then it’s about time you learn it. It’s pretty easy.

Use npm help json to learn which fields npm cares about. Basically, it’s as simple as putting the package.json file in the root of your project, and then telling it how to get to your code.

Seriously. It’s incredibly easy. If you disagree, please let me know.

Acquiring Fame: npm publish

So, you created a package, and you can install it. Now you want the everlasting fame and glory that comes with other people using your code. There is no better way to ensure your immortality than eventually being a part of every web app out there, and the best—nay, the ONLY—way to truly accomplish this is to publish nodejs packages.

First, create a user account with npm adduser. Give it a username, password, and email address, and it’ll create an account on the npm registry. (You can also use adduser to authorize a user account on a new machine, or fix the situation if you break your configs.)

Next, go to the root of your package code, and do npm publish.

Bam. Done.

Now go to the mailing list and tell everyone how much more awesome they’d be if they used your program.

Dependency Hell Isn’t Fun

Most systems have a single root namespace. That kind of sucks. If two different things depend on different versions of the same dependency, then you’ve got two options:

1. Statically compile the dependency into the program.
2. Hate life.

Option #2 is Not Fun. So eff that noise. That sucks, and is dumb.

Option #1 is less than ideal if you want to be able to abstract out parts of your program and benefit from updates to the dependencies.

Thankfully, unlike most programming environments, the CommonJS Securable Module system lets you avoid dependency hell by modifying the require.paths at runtime, so that each package sees the version that it depends on.

I think that’s pretty cool.

What to do when npm lets you down

npm’s pretty young software, and still being actively developed. Especially if you find yourself using some newer features, occasionally npm will have a bug. Or, perhaps equally likely, you’ll need npm to do something that it doesn’t yet do, and want to request a feature.

You can post bugs and feature requests on the issues page. If you want to ask general questions, you can ask on the google group.

Or, if you’re more the instant gratification type, you can come ask questions in IRC on the #node.js channel on freenode.net. If I’m there, I’ll try to help you out, but this community continues to impress me with its helpfulness. Noders rock!

It occurs to me that I’ve not updated this blog at all this year. Don’t worry, this isn’t some kind of apology post, it’s just that it occurs to me that the conversation has become increasingly less about large essay-like missives to the tech world at large, and more about targeted communication to subject-matter …Read More

My last day at Yahoo will be 2010-01-22.

Yahoo has been a mostly great company to work for, and YUI is by far the best team that I’ve worked on here. It’s a shame that I didn’t join YUI sooner; I still feel like I just got here. The quality of this team made …Read More

Here is an example of a very simple lighttpd/nginx-style web server written in NodeJS.

I’ve called it simple-node-server or “sns” for short, and you can fork it on my github account.

There are a lot of folks building SSJS clones of Django and WSGI and Rack the like. However, Python and Ruby have blocking IO, and …Read More

Lot going on this summer. My roommate moved back to CT, meaning that I had to buy a car and get a new apartment. I moved from the YAP team to the YUI team. Also, I’ve been spending more and more of my free time playing around with server-side Javascript, specifically Narwhal …Read More

Partly because I haven’t been writing much CSS these days, and partly because it’s been just over a year since the last redesign, I felt like this site needed a face lift.

Fonts

I’ve been getting more and more excited about the impending freedom of the @font-face CSS declaration. The prospect using any true-type or open-type …Read More