diff options
author | isaacs <i@izs.me> | 2010-05-14 11:34:22 +0400 |
---|---|---|
committer | isaacs <i@izs.me> | 2010-05-14 11:34:22 +0400 |
commit | 83b9faaab0da141c16744da8f3f6a877888acb86 (patch) | |
tree | db491a92da40ca02cc3bb662a43f52b47a1e395b /doc | |
parent | f2a3e45b88849d66e6f0b66351f83842ad2304b8 (diff) |
Documentation for developers using npm
Diffstat (limited to 'doc')
-rw-r--r-- | doc/developers.md | 141 |
1 files changed, 141 insertions, 0 deletions
diff --git a/doc/developers.md b/doc/developers.md new file mode 100644 index 000000000..325a43efa --- /dev/null +++ b/doc/developers.md @@ -0,0 +1,141 @@ +npm-developers(1) -- Developer Guide +==================================== + +## DESCRIPTION + +So, you've decided to use npm to publish your project. + +Fantastic! + +There are a few things that you need to do above the simple steps +that your users will do to install your program. + +## About These Documents + +These are man pages. If you install npm, you should be able to +then do `man npm-thing` to get the documentation on a particular +topic. + +Any time you see "see npm-whatever(1)", you can do `man npm-whatever` +to get at the docs. + +## The package.json File + +You need to have a `package.json` file in the root of your project. + +See npm-json(1) for details about what goes in that file. At the very +least, you need: + +* name: + This should be a string that identifies your project. Please do not + use the name to specify that it runs on node, or is in JavaScript. + You can use the "engines" field to explicitly state the versions of + node (or whatever else) that your program requires, and it's pretty + well assumed that it's javascript. + + It does not necessarily need to match your github repository name. + + So, `node-foo` and `bar-js` are bad names. `foo` or `bar` are better. + +* version: + A semver-compatible version. + +* engines: + Specify the versions of node (or whatever else) that your program + runs on. The node API changes a lot, and there may be bugs or new + functionality that you depend on. Be explicit. + +* author: + Take some credit. + +* scripts: + If you have a special compilation or installation script, then you + should put it in the `scripts` hash. See npm-scripts(1). + +* main: + If you have a single module that serves as the entry point to your + program (like what the "foo" package gives you at require("foo")), + then you need to specify that in the "main" field. + +## Make Sure Your Package Installs and Works + +**This is important.** + +If you can not install it locally, you'll have +problems trying to publish it. Or, worse yet, you'll be able to +publish it, but you'll be publishing a broken or pointless package. +So don't do that. + +In the root of your package, do this: + + npm install . + +That'll show you that it's working. If you'd rather just create a symlink +package that points to your working directory, then do this: + + npm link . + +Use `npm ls | grep @installed` to see if it's there. + +Then go into the node-repl, and try using require() to bring in your module's +main and libs things. Assuming that you have a package like this: + + node_foo/ + lib/ + foo.js + bar.js + +and you define your package.json with this in it: + + { "name" : "foo" + , "directories" : { "lib" : "./lib" } + , "main" : "./lib/foo" + } + +then you'd want to make sure that require("foo") and require("foo/bar") both +work and bring in the appropriate modules. + +## Compile Node with OpenSSL + +npm will stubbornly refuse to expose your password in the clear. That +means that you'll have to install whatever package provides openssl.h +on your system. When you `./configure` node, make sure that it says: + + Checking for openssl : yes + +## Create a User Account + +Create a user with the adduser command. It works like this: + + npm adduser bob password bob@email.com + +This is documented better in npm-adduser(1). So do this to get the +details: + + man npm-adduser + +## Publish your package + +This part's easy. + + npm publish /path/to/my-package + +You can give publish a url to a tarball, or a filename of a tarball, +or a path to a folder. (Paths have to either be "." or contain a "/".) + +## Tag your package as "stable" + +This makes it easier to install without your users having to know the +version ahead of time. + + npm tag my-package 1.2.3 stable + +You can also use other tags, but "stable" and "latest" have reserved +meanings. + +## Brag about it + +Send emails, write blogs, blab in IRC. + +Tell the world how easy it is to install your program! + |