Permalink
Browse files

Port article about npm

  • Loading branch information...
1 parent a8a2554 commit 05896bb828f0d7e9251dd5b4cfd72350896990bd @creationix committed Sep 11, 2010
Showing with 223 additions and 0 deletions.
  1. +223 −0 articles/introduction-to-npm.markdown
@@ -0,0 +1,223 @@
+Title: Introduction to npm
+Author: Node Knockout
+Date: Sat, 11 Sep 2010 23:05:24 GMT
+Node: v0.2.1
+
+This was the third in a series of posts leading up to
+[Node.js Knockout][] on how to use [node.js][]. This post was
+written by [npm][] author and [Node.js Knockout judge][] Isaac
+Schlueter.
+
+npm is a [NodeJS][node.js] 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][node.js]. 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 http://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.
+
+`</rant>`
+
+## 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!
+
+ [Countdown to Knockout: Post 3 - Introduction to npm]: http://nodeknockout.posterous.com/countdown-to-knockout-post-3-introduction-to
+ [Node.js Knockout]: http://nodeknockout.com/
+ [node.js]: http://nodejs.org/
+ [npm]: http://npmjs.org
+ [Node.js Knockout judge]: http://nodeknockout.com/judging#isaac_schlueter
+ [latest code]: http://github.com/isaacs/npm
+ [Marak]: http://jimbastard.com/
+ [json]: http://json.org/
+ [let me know]: mailto:i@izs.me
+ [the issues page]: http://github.com/isaacs/npm/issues
+ [the google group]: http://groups.google.com/group/npm-
+ [the #node.js channel on freenode.net]: irc://irc.freenode.net/#node.js

0 comments on commit 05896bb

Please sign in to comment.