| .\" Generated with Ronnjs 0.3.8 |
| .\" http://github.com/kapouer/ronnjs/ |
| . |
| .TH "NPM\-DEVELOPERS" "7" "December 2013" "" "" |
| . |
| .SH "NAME" |
| \fBnpm-developers\fR \-\- Developer Guide |
| . |
| .SH "DESCRIPTION" |
| So, you\'ve decided to use npm to develop (and maybe publish/deploy) |
| your project\. |
| . |
| .P |
| Fantastic! |
| . |
| .P |
| There are a few things that you need to do above the simple steps |
| that your users will do to install your program\. |
| . |
| .SH "About These Documents" |
| These are man pages\. If you install npm, you should be able to |
| then do \fBman npm\-thing\fR to get the documentation on a particular |
| topic, or \fBnpm help thing\fR to see the same information\. |
| . |
| .SH "What is a " |
| A package is: |
| . |
| .IP "\(bu" 4 |
| a) a folder containing a program described by a package\.json file |
| . |
| .IP "\(bu" 4 |
| b) a gzipped tarball containing (a) |
| . |
| .IP "\(bu" 4 |
| c) a url that resolves to (b) |
| . |
| .IP "\(bu" 4 |
| d) a \fB<name>@<version>\fR that is published on the registry with (c) |
| . |
| .IP "\(bu" 4 |
| e) a \fB<name>@<tag>\fR that points to (d) |
| . |
| .IP "\(bu" 4 |
| f) a \fB<name>\fR that has a "latest" tag satisfying (e) |
| . |
| .IP "\(bu" 4 |
| g) a \fBgit\fR url that, when cloned, results in (a)\. |
| . |
| .IP "" 0 |
| . |
| .P |
| Even if you never publish your package, you can still get a lot of |
| benefits of using npm if you just want to write a node program (a), and |
| perhaps if you also want to be able to easily install it elsewhere |
| after packing it up into a tarball (b)\. |
| . |
| .P |
| Git urls can be of the form: |
| . |
| .IP "" 4 |
| . |
| .nf |
| git://github\.com/user/project\.git#commit\-ish |
| git+ssh://user@hostname:project\.git#commit\-ish |
| git+http://user@hostname/project/blah\.git#commit\-ish |
| git+https://user@hostname/project/blah\.git#commit\-ish |
| . |
| .fi |
| . |
| .IP "" 0 |
| . |
| .P |
| The \fBcommit\-ish\fR can be any tag, sha, or branch which can be supplied as |
| an argument to \fBgit checkout\fR\|\. The default is \fBmaster\fR\|\. |
| . |
| .SH "The package\.json File" |
| You need to have a \fBpackage\.json\fR file in the root of your project to do |
| much of anything with npm\. That is basically the whole interface\. |
| . |
| .P |
| npm help See \fBpackage\.json\fR for details about what goes in that file\. At the very |
| least, you need: |
| . |
| .IP "\(bu" 4 |
| 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\. |
| . |
| .IP |
| It does not necessarily need to match your github repository name\. |
| . |
| .IP |
| So, \fBnode\-foo\fR and \fBbar\-js\fR are bad names\. \fBfoo\fR or \fBbar\fR are better\. |
| . |
| .IP "\(bu" 4 |
| version: |
| A semver\-compatible version\. |
| . |
| .IP "\(bu" 4 |
| 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\. |
| . |
| .IP "\(bu" 4 |
| author: |
| Take some credit\. |
| . |
| .IP "\(bu" 4 |
| scripts: |
| If you have a special compilation or installation script, then you |
| should put it in the \fBscripts\fR hash\. You should definitely have at |
| least a basic smoke\-test command as the "scripts\.test" field\. |
| npm help See npm\-scripts\. |
| . |
| .IP "\(bu" 4 |
| 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\. |
| . |
| .IP "\(bu" 4 |
| directories: |
| This is a hash of folders\. The best ones to include are "lib" and |
| "doc", but if you specify a folder full of man pages in "man", then |
| they\'ll get installed just like these ones\. |
| . |
| .IP "" 0 |
| . |
| .P |
| You can use \fBnpm init\fR in the root of your package in order to get you |
| npm help started with a pretty basic package\.json file\. See \fBnpm\-init\fR for |
| more info\. |
| . |
| .SH "Keeping files " |
| Use a \fB\|\.npmignore\fR file to keep stuff out of your package\. If there\'s |
| no \fB\|\.npmignore\fR file, but there \fIis\fR a \fB\|\.gitignore\fR file, then npm will |
| ignore the stuff matched by the \fB\|\.gitignore\fR file\. If you \fIwant\fR to |
| include something that is excluded by your \fB\|\.gitignore\fR file, you can |
| create an empty \fB\|\.npmignore\fR file to override it\. |
| . |
| .P |
| By default, the following paths and files are ignored, so there\'s no |
| need to add them to \fB\|\.npmignore\fR explicitly: |
| . |
| .IP "\(bu" 4 |
| \fB\|\.*\.swp\fR |
| . |
| .IP "\(bu" 4 |
| \fB\|\._*\fR |
| . |
| .IP "\(bu" 4 |
| \fB\|\.DS_Store\fR |
| . |
| .IP "\(bu" 4 |
| \fB\|\.git\fR |
| . |
| .IP "\(bu" 4 |
| \fB\|\.hg\fR |
| . |
| .IP "\(bu" 4 |
| \fB\|\.lock\-wscript\fR |
| . |
| .IP "\(bu" 4 |
| \fB\|\.svn\fR |
| . |
| .IP "\(bu" 4 |
| \fB\|\.wafpickle\-*\fR |
| . |
| .IP "\(bu" 4 |
| \fBCVS\fR |
| . |
| .IP "\(bu" 4 |
| \fBnpm\-debug\.log\fR |
| . |
| .IP "" 0 |
| . |
| .P |
| Additionally, everything in \fBnode_modules\fR is ignored, except for |
| bundled dependencies\. npm automatically handles this for you, so don\'t |
| bother adding \fBnode_modules\fR to \fB\|\.npmignore\fR\|\. |
| . |
| .P |
| The following paths and files are never ignored, so adding them to \fB\|\.npmignore\fR is pointless: |
| . |
| .IP "\(bu" 4 |
| \fBpackage\.json\fR |
| . |
| .IP "\(bu" 4 |
| \fBREADME\.*\fR |
| . |
| .IP "" 0 |
| . |
| .SH "Link Packages" |
| \fBnpm link\fR is designed to install a development package and see the |
| changes in real time without having to keep re\-installing it\. (You do |
| need to either re\-link or \fBnpm rebuild \-g\fR to update compiled packages, |
| of course\.) |
| . |
| .P |
| npm help More info at \fBnpm\-link\fR\|\. |
| . |
| .SH "Before Publishing: Make Sure Your Package Installs and Works" |
| \fBThis is important\.\fR |
| . |
| .P |
| 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\. |
| . |
| .P |
| In the root of your package, do this: |
| . |
| .IP "" 4 |
| . |
| .nf |
| npm install \. \-g |
| . |
| .fi |
| . |
| .IP "" 0 |
| . |
| .P |
| 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: |
| . |
| .IP "" 4 |
| . |
| .nf |
| npm link |
| . |
| .fi |
| . |
| .IP "" 0 |
| . |
| .P |
| Use \fBnpm ls \-g\fR to see if it\'s there\. |
| . |
| .P |
| To test a local install, go into some other folder, and then do: |
| . |
| .IP "" 4 |
| . |
| .nf |
| cd \.\./some\-other\-folder |
| npm install \.\./my\-package |
| . |
| .fi |
| . |
| .IP "" 0 |
| . |
| .P |
| to install it locally into the node_modules folder in that other place\. |
| . |
| .P |
| Then go into the node\-repl, and try using require("my\-thing") to |
| bring in your module\'s main module\. |
| . |
| .SH "Create a User Account" |
| Create a user with the adduser command\. It works like this: |
| . |
| .IP "" 4 |
| . |
| .nf |
| npm adduser |
| . |
| .fi |
| . |
| .IP "" 0 |
| . |
| .P |
| and then follow the prompts\. |
| . |
| .P |
| npm help This is documented better in npm\-adduser\. |
| . |
| .SH "Publish your package" |
| This part\'s easy\. IN the root of your folder, do this: |
| . |
| .IP "" 4 |
| . |
| .nf |
| npm publish |
| . |
| .fi |
| . |
| .IP "" 0 |
| . |
| .P |
| You can give publish a url to a tarball, or a filename of a tarball, |
| or a path to a folder\. |
| . |
| .P |
| Note that pretty much \fBeverything in that folder will be exposed\fR |
| by default\. So, if you have secret stuff in there, use a \fB\|\.npmignore\fR file to list out the globs to ignore, or publish |
| from a fresh checkout\. |
| . |
| .SH "Brag about it" |
| Send emails, write blogs, blab in IRC\. |
| . |
| .P |
| Tell the world how easy it is to install your program! |
| . |
| .SH "SEE ALSO" |
| . |
| .IP "\(bu" 4 |
| npm help faq |
| . |
| .IP "\(bu" 4 |
| npm help npm |
| . |
| .IP "\(bu" 4 |
| npm help init |
| . |
| .IP "\(bu" 4 |
| npm help package\.json |
| . |
| .IP "\(bu" 4 |
| npm help scripts |
| . |
| .IP "\(bu" 4 |
| npm help publish |
| . |
| .IP "\(bu" 4 |
| npm help adduser |
| . |
| .IP "\(bu" 4 |
| npm help registry |
| . |
| .IP "" 0 |
| |