@ -22,7 +22,7 @@ element in the array tells config what to do. Possible values are:</p>
<ul><li><p><code>set</code></p><p>Sets a config parameter. The second element in <code>args</code> is interpreted as the
key, and the third element is interpreted as the value.</p></li><li><p><code>get</code></p><p>Gets the value of a config parameter. The second element in <code>args</code> is the
key to get the value of.</p></li><li><p><code>delete</code> (<code>rm</code> or <code>del</code>)</p><p>Deletes a parameter from the config. The second element in <code>args</code> is the
key to delete.</p></li><li><p><code>list</code> (<code>ls</code>)</p><p>Show all configs that aren't secret. No parameters necessary.</p></li><li><p><code>edit</code>:</p><p>Opens the config file in the default editor. This command isn't very useful
key to delete.</p></li><li><p><code>list</code> (<code>ls</code>)</p><p>Show all configs that aren't secret. No parameters necessary.</p></li><li><p><code>edit</code>:</p><p>Opens the config file in the default editor. This command isn't very useful
programmatically, but it is made available.</p></li></ul>
<p>To programmatically access npm configuration settings, or set them for
<p>Note that the package is <em>not</em> automatically rebuilt afterwards, so be
sure to use <code>npm rebuild <pkg></code> if you make any changes.</p>
<p>The first element in the 'args' parameter must be a package name. After that is the optional command, which can be any number of strings. All of the strings will be combined into one, space-delimited command.</p>
<p>The first element in the 'args' parameter must be a package name. After that is the optional command, which can be any number of strings. All of the strings will be combined into one, space-delimited command.</p>
@ -32,7 +32,7 @@ npm.load(configObject, function (er, npm) {
To find documentation of the command line
client, see <code><ahref="../doc/npm.html">npm(1)</a></code>.</p>
<p>Prior to using npm's commands,
<p>Prior to using npm's commands,
<code>npm.load()</code> must be called with an object hash of
top-level configs. In the npm command line client,
this set of configs is parsed from the command line options. Additional
@ -57,9 +57,9 @@ command.</p>
<ul><li><p><code>npm.load(configs, cb)</code></p><p>Load the configuration params, and call the <code>cb</code> function once the
globalconfig and userconfig files have been loaded as well, or on
nextTick if they've already been loaded.</p></li><li><p><code>npm.config</code></p><p>An object for accessing npm configuration parameters.</p><ul><li><p><code>npm.config.get(key)</code></p></li><li><code>npm.config.set(key, val)</code></li><li><p><code>npm.config.del(key)</code></p></li></ul></li><li><p><code>npm.dir</code> or <code>npm.root</code></p><p>The <code>node_modules</code> directory where npm will operate.</p></li><li><p><code>npm.prefix</code></p><p>The prefix where npm is operating. (Most often the current working
nextTick if they've already been loaded.</p></li><li><p><code>npm.config</code></p><p>An object for accessing npm configuration parameters.</p><ul><li><p><code>npm.config.get(key)</code></p></li><li><code>npm.config.set(key, val)</code></li><li><p><code>npm.config.del(key)</code></p></li></ul></li><li><p><code>npm.dir</code> or <code>npm.root</code></p><p>The <code>node_modules</code> directory where npm will operate.</p></li><li><p><code>npm.prefix</code></p><p>The prefix where npm is operating. (Most often the current working
directory.)</p></li><li><p><code>npm.cache</code></p><p>The place where npm keeps JSON and tarballs it fetches from the
registry (or uploads to the registry).</p></li><li><p><code>npm.tmp</code></p><p>npm's temporary working directory.</p></li><li><p><code>npm.deref</code></p><p>Get the "real" name for a command that has either an alias or
registry (or uploads to the registry).</p></li><li><p><code>npm.tmp</code></p><p>npm's temporary working directory.</p></li><li><p><code>npm.deref</code></p><p>Get the "real" name for a command that has either an alias or
abbreviation.</p></li></ul>
<h2id="MAGIC">MAGIC</h2>
@ -74,11 +74,11 @@ the error or results.</p>
<p>For example, this would work in a node repl:</p>
Array of search terms. These terms are case-insensitive.</li><li>silent:
If true, npm will not log anything to the console.</li><li>staleness:
This is the threshold for stale packages. "Fresh" packages are not refreshed
This is the threshold for stale packages. "Fresh" packages are not refreshed
from the registry. This value is measured in seconds.</li><li><p>callback:
Returns an object where each key is the name of a package, and the value
is information about that package along with a 'words' property, which is
is information about that package along with a 'words' property, which is
a space-delimited string of all of the interesting words in that package.
The only properties included are those that are searched, which generally include:</p><ul><li>name</li><li>description</li><li>maintainers</li><li>url</li><li>keywords</li></ul></li></ul>
<p>A search on the registry excludes any result that does not match all of the
search terms. It also removes any items from the results that contain an
excluded term (the "searchexclude" config). The search is case insensitive
and doesn't try to read your mind (it doesn't do any verb tense matching or the
excluded term (the "searchexclude" config). The search is case insensitive
and doesn't try to read your mind (it doesn't do any verb tense matching or the
<p>Updates a package, upgrading it to the latest version. It also installs any missing packages.</p>
<p>The 'packages' argument is an array of packages to update. The 'callback' parameter will be called when done or when an error occurs.</p>
<p>The 'packages' argument is an array of packages to update. The 'callback' parameter will be called when done or when an error occurs.</p>
sudo make install # (or: `node cli.js install -gf`)</code></pre>
<p>If you're sitting in the code folder reading this document in your
terminal, then you've already got the code. Just do:</p>
<pre><code>sudo make install</code></pre>
<p>and npm will install itself.</p>
<h2id="Permissions-when-Using-npm-to-Install-Other-Stuff">Permissions when Using npm to Install Other Stuff</h2>
<p><strong>tl;dr</strong></p>
<ul><li>Use <code>sudo</code> for greater safety. Or don't, if you prefer not to.</li><li>npm will downgrade permissions if it's root before running any build
<ul><li>Use <code>sudo</code> for greater safety. Or don't, if you prefer not to.</li><li>npm will downgrade permissions if it's root before running any build
scripts that package authors specified.</li></ul>
<h3id="More-details">More details...</h3>
@ -122,7 +94,7 @@ to running any package build or test commands.</p>
support uid switching, then npm will not attempt to change the userid.</p>
<p>If you would like to ensure that npm <strong>always</strong> runs scripts as the
"nobody" user, and have it fail if it cannot downgrade permissions, then
"nobody" user, and have it fail if it cannot downgrade permissions, then
set the following configuration param:</p>
<pre><code>npm config set unsafe-perm false</code></pre>
@ -142,7 +114,7 @@ set the following configuration param:</p>
<h2id="More-Severe-Uninstalling">More Severe Uninstalling</h2>
<p>Usually, the above instructions are sufficient. That will remove
npm, but leave behind anything you've installed.</p>
npm, but leave behind anything you've installed.</p>
<p>If you would like to remove all the packages that you have installed,
then you can use the <code>npm ls</code> command to find them, and then <code>npm rm</code> to
<ul><li>Update request to support HTTPS-over-HTTP proxy tunneling</li><li>Throw on undefined envs in config settings</li><li>Update which to 1.0.5</li><li>Fix windows UNC busyloop in findPrefix</li><li>Bundle nested bundleDependencies properly</li><li>Alias adduser to add-user</li><li>Doc updates (Christian Howe, Henrik Hodne, Andrew Lunny)</li><li>ignore logfd/outfd streams in makeEnv() (Rod Vagg)</li><li>shrinkwrap: Behave properly with url-installed deps</li><li>install: Support --save with url install targets</li><li>Support installing naked tars or single-file modules from urls etc.</li><li>init: Don't add engines section</li><li>Don't run make clean on rebuild</li><li>Added missing unicode replacement (atomizer)</li></ul>
<ul><li>Update request to support HTTPS-over-HTTP proxy tunneling</li><li>Throw on undefined envs in config settings</li><li>Update which to 1.0.5</li><li>Fix windows UNC busyloop in findPrefix</li><li>Bundle nested bundleDependencies properly</li><li>Alias adduser to add-user</li><li>Doc updates (Christian Howe, Henrik Hodne, Andrew Lunny)</li><li>ignore logfd/outfd streams in makeEnv() (Rod Vagg)</li><li>shrinkwrap: Behave properly with url-installed deps</li><li>install: Support --save with url install targets</li><li>Support installing naked tars or single-file modules from urls etc.</li><li>init: Don't add engines section</li><li>Don't run make clean on rebuild</li><li>Added missing unicode replacement (atomizer)</li></ul>
<h3id="1-1-2">1.1.2</h3>
<p>Dave Pacheco (2):
add "npm shrinkwrap"</p>
add "npm shrinkwrap"</p>
<p>Martin Cooper (1):
Fix #1753 Make a copy of the cached objects we'll modify.</p>
Fix #1753 Make a copy of the cached objects we'll modify.</p>
<p>Tim Oxley (1):
correctly remove readme from default npm view command.</p>
@ -32,7 +32,7 @@
update minimatch
update request
Experimental: single-file modules
Fix #2172 Don't remove global mans uninstalling local pkgs
Fix #2172 Don't remove global mans uninstalling local pkgs
Add --versions flag to show the version of node as well
Support --json flag for ls output
update request to 2.9.151</p>
@ -47,11 +47,11 @@
<h3id="0-3">0.3</h3>
<ul><li>More correct permission/uid handling when running as root </li><li>Require node 0.4.0 </li><li>Reduce featureset </li><li>Packages without "main" modules don't export modules</li><li>Remove support for invalid JSON (since node doesn't support it)</li></ul>
<ul><li>More correct permission/uid handling when running as root </li><li>Require node 0.4.0 </li><li>Reduce featureset </li><li>Packages without "main" modules don't export modules</li><li>Remove support for invalid JSON (since node doesn't support it)</li></ul>
<h3id="0-2">0.2</h3>
<ul><li>First allegedly "stable" release</li><li>Most functionality implemented </li><li>Used shim files and <code>name@version</code> symlinks</li><li>Feature explosion</li><li>Kind of a mess</li></ul>
<ul><li>First allegedly "stable" release</li><li>Most functionality implemented </li><li>Used shim files and <code>name@version</code> symlinks</li><li>Feature explosion</li><li>Kind of a mess</li></ul>
<p>If a block needs to wrap to the next line, use a curly brace. Don't
use it if it doesn't.</p>
<p>If a block needs to wrap to the next line, use a curly brace. Don't
use it if it doesn't.</p>
<p>Bad:</p>
@ -61,10 +61,10 @@ while (foo) {
<h2id="Semicolons">Semicolons</h2>
<p>Don't use them except in four situations:</p>
<p>Don't use them except in four situations:</p>
<ul><li><code>for (;;)</code> loops. They're actually required.</li><li>null loops like: <code>while (something) ;</code> (But you'd better have a good
reason for doing that.)</li><li><code>case "foo": doSomething(); break</code></li><li>In front of a leading <code>(</code> or <code>[</code> at the start of the line.
<ul><li><code>for (;;)</code> loops. They're actually required.</li><li>null loops like: <code>while (something) ;</code> (But you'd better have a good
reason for doing that.)</li><li><code>case "foo": doSomething(); break</code></li><li>In front of a leading <code>(</code> or <code>[</code> at the start of the line.
This prevents the expression from being interpreted
as a function call or property access, respectively.</li></ul>
@ -74,9 +74,9 @@ as a function call or property access, respectively.</li></ul>
;[a, b, c].forEach(doSomething)
for (var i = 0; i < 10; i ++) {
switch (state) {
case "begin": start(); continue
case "end": finish(); break
default: throw new Error("unknown state")
case "begin": start(); continue
case "end": finish(); break
default: throw new Error("unknown state")
}
end()
}</code></pre>
@ -91,15 +91,15 @@ across multiple lines, put the comma at the start of the next
line, directly below the token that starts the list. Put the
final token in the list on a line by itself. For example:</p>
<p>So, you've decided to use npm to develop (and maybe publish/deploy)
<p>So, you've decided to use npm to develop (and maybe publish/deploy)
your project.</p>
<p>Fantastic!</p>
@ -24,11 +24,11 @@ that your users will do to install your program.</p>
then do <code>man npm-thing</code> to get the documentation on a particular
topic, or <code>npm help thing</code> to see the same information.</p>
<h2id="What-is-a-package">What is a `package`</h2>
<h2id="What-is-a-package">What is a <code>package</code></h2>
<p>A package is:</p>
<ul><li>a) a folder containing a program described by a package.json file</li><li>b) a gzipped tarball containing (a)</li><li>c) a url that resolves to (b)</li><li>d) a <code><name>@<version></code> that is published on the registry with (c)</li><li>e) a <code><name>@<tag></code> that points to (d)</li><li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li><li>g) a <code>git</code> url that, when cloned, results in (a).</li></ul>
<ul><li>a) a folder containing a program described by a package.json file</li><li>b) a gzipped tarball containing (a)</li><li>c) a url that resolves to (b)</li><li>d) a <code><name>@<version></code> that is published on the registry with (c)</li><li>e) a <code><name>@<tag></code> that points to (d)</li><li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li><li>g) a <code>git</code> url that, when cloned, results in (a).</li></ul>
<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
@ -56,9 +56,9 @@ least, you need:</p>
<ul><li><p>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.</p><p>It does not necessarily need to match your github repository name.</p><p>So, <code>node-foo</code> and <code>bar-js</code> are bad names. <code>foo</code> or <code>bar</code> are better.</p></li><li><p>version:
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.</p><p>It does not necessarily need to match your github repository name.</p><p>So, <code>node-foo</code> and <code>bar-js</code> are bad names. <code>foo</code> or <code>bar</code> are better.</p></li><li><p>version:
A semver-compatible version.</p></li><li><p>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
@ -66,22 +66,22 @@ functionality that you depend on. Be explicit.</p></li><li><p>author:
Take some credit.</p></li><li><p>scripts:
If you have a special compilation or installation script, then you
should put it in the <code>scripts</code> hash. You should definitely have at
least a basic smoke-test command as the "scripts.test" field.
least a basic smoke-test command as the "scripts.test" field.
See <ahref="../doc/scripts.html">scripts(1)</a>.</p></li><li><p>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.</p></li><li><p>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.</p></li></ul>
program (like what the "foo" package gives you at require("foo")),
then you need to specify that in the "main" field.</p></li><li><p>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.</p></li></ul>
<p>You can use <code>npm init</code> in the root of your package in order to get you
started with a pretty basic package.json file. See <code><ahref="../doc/init.html">init(1)</a></code> for
more info.</p>
<h2id="Keeping-files-out-of-your-package">Keeping files *out* of your package</h2>
<h2id="Keeping-files-out-of-your-package">Keeping files <em>out</em> of your package</h2>
<p>Use a <code>.npmignore</code> file to keep stuff out of your package. If there's
<p>Use a <code>.npmignore</code> file to keep stuff out of your package. If there's
no .npmignore file, but there <em>is</em> a .gitignore file, then npm will
ignore the stuff matched by the .gitignore file. If you <em>want</em> to
include something that is excluded by your .gitignore file, you can
@ -100,21 +100,21 @@ of course.)</p>
<p><strong>This is important.</strong></p>
<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>
<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>
<p>In the root of your package, do this:</p>
<pre><code>npm install . -g</code></pre>
<p>That'll show you that it's working. If you'd rather just create a symlink
<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:</p>
<pre><code>npm link</code></pre>
<p>Use <code>npm ls -g</code> to see if it's there.</p>
<p>Use <code>npm ls -g</code> to see if it's there.</p>
<p>To test a local install, go into some other folder, and then do:</p>
<ol><li>Get the author email with <code>npm owner ls <pkgname></code></li><li>Email the author, CC <ahref="mailto:i@izs.me">i@izs.me</a>.</li><li>After a few weeks, if there's no resolution, we'll sort it out.</li></ol>
<ol><li>Get the author email with <code>npm owner ls <pkgname></code></li><li>Email the author, CC <ahref="mailto:i@izs.me">i@izs.me</a>.</li><li>After a few weeks, if there's no resolution, we'll sort it out.</li></ol>
<h2id="DESCRIPTION">DESCRIPTION</h2>
@ -19,14 +19,14 @@ later, some other user wants to use that name. Here are some common
ways that happens (each of these is based on actual events.)</p>
<ol><li>Bob writes a JavaScript module <code>foo</code>, which is not node-specific.
Bob doesn't use node at all. Joe wants to use <code>foo</code> in node, so he
Bob doesn't use node at all. Joe wants to use <code>foo</code> in node, so he
wraps it in an npm module. Some time later, Bob starts using node,
and wants to take over management of his program.</li><li>Bob writes an npm module <code>foo</code>, and publishes it. Perhaps much
later, Joe finds a bug in <code>foo</code>, and fixes it. He sends a pull
request to Bob, but Bob doesn't have the time to deal with it,
request to Bob, but Bob doesn't have the time to deal with it,
because he has a new job and a new baby and is focused on his new
erlang project, and kind of not involved with node any more. Joe
would like to publish a new <code>foo</code>, but can't, because the name is
would like to publish a new <code>foo</code>, but can't, because the name is
taken.</li><li>Bob writes a 10-line flow-control library, and calls it <code>foo</code>, and
publishes it to the npm registry. Being a simple little thing, it
never really has to be updated. Joe works for Foo Inc, the makers
@ -35,10 +35,10 @@ toolkit framework. They publish it to npm as <code>foojs</code>, but people are
routinely confused when <code>npm install foo</code> is some different thing.</li><li>Bob writes a parser for the widely-known <code>foo</code> file format, because
he needs it for work. Then, he gets a new job, and never updates the
prototype. Later on, Joe writes a much more complete <code>foo</code> parser,
but can't publish, because Bob's <code>foo</code> is in the way.</li></ol>
but can't publish, because Bob's <code>foo</code> is in the way.</li></ol>
<p>The validity of Joe's claim in each situation can be debated. However,
Joe's appropriate course of action in each case is the same.</p>
<p>The validity of Joe's claim in each situation can be debated. However,
Joe's appropriate course of action in each case is the same.</p>
<ol><li><code>npm owner ls foo</code>. This will tell Joe the email address of the
owner (Bob).</li><li>Joe emails Bob, explaining the situation <strong>as respecfully as possible</strong>,
@ -46,15 +46,15 @@ and what he would like to do with the module name. He adds
isaacs <ahref="mailto:i@izs.me">i@izs.me</a> to the CC list of the email. Mention in the email
that Bob can run <code>npm owner add joe foo</code> to add Joe as an owner of
the <code>foo</code> package.</li><li>After a reasonable amount of time, if Bob has not responded, or if
Bob and Joe can't come to any sort of resolution, email isaacs
<ahref="mailto:i@izs.me">i@izs.me</a> and we'll sort it out.</li></ol>
Bob and Joe can't come to any sort of resolution, email isaacs
<ahref="mailto:i@izs.me">i@izs.me</a> and we'll sort it out.</li></ol>
<h2id="REASONING">REASONING</h2>
<p>In almost every case so far, the parties involved have been able to reach
an amicable resolution without any major intervention. Most people
really do want to be reasonable, and are probably not even aware that
they're in your way.</p>
they're in your way.</p>
<p>Module ecosystems are most vibrant and powerful when they are as
self-directed as possible. If an admin one day deletes something you
<p>to open these documents in your default web browser rather than <code>man</code>.</p>
<h2id="It-didn-t-work">It didn't work.</h2>
<h2id="It-didn-t-work">It didn't work.</h2>
<p>That's not really a question.</p>
<p>That's not really a question.</p>
<h2id="Why-didn-t-it-work">Why didn't it work?</h2>
<h2id="Why-didn-t-it-work">Why didn't it work?</h2>
<p>I don't know yet.</p>
<p>I don't know yet.</p>
<p>Read the error output, and if you can't figure out what it means,
<p>Read the error output, and if you can't figure out what it means,
do what it says and post a bug with all the information it asks for.</p>
<h2id="Where-does-npm-put-stuff">Where does npm put stuff?</h2>
@ -44,22 +44,22 @@ and its modules go in <code>npm root -g</code>.</li></ul>
is especially important for command line utilities that need to add
their bins to the global system <code>PATH</code>.)</p>
<h2id="I-installed-something-globally-but-I-can-t-require-it">I installed something globally, but I can't `require()` it</h2>
<h2id="I-installed-something-globally-but-I-can-t-require-it">I installed something globally, but I can't <code>require()</code> it</h2>
<p>Install it locally.</p>
<p>The global install location is a place for command-line utilities
to put their bins in the system <code>PATH</code>. It's not for use with <code>require()</code>.</p>
to put their bins in the system <code>PATH</code>. It's not for use with <code>require()</code>.</p>
<p>If you <code>require()</code> a module in your code, then that means it's a
<p>If you <code>require()</code> a module in your code, then that means it's a
dependency, and a part of your program. You need to install it locally
in your program.</p>
<h2id="Why-can-t-npm-just-put-everything-in-one-place-like-other-package-managers">Why can't npm just put everything in one place, like other package managers?</h2>
<h2id="Why-can-t-npm-just-put-everything-in-one-place-like-other-package-managers">Why can't npm just put everything in one place, like other package managers?</h2>
<p>Not every change is an improvement, but every improvement is a change.
This would be like asking git to do network IO for every commit. It's
not going to happen, because it's a terrible idea that causes more
This would be like asking git to do network IO for every commit. It's
not going to happen, because it's a terrible idea that causes more
problems than it solves.</p>
<p>It is much harder to avoid dependency conflicts without nesting
@ -69,16 +69,16 @@ more details.</p>
<p>If you want a package to be installed in one place, and have all your
programs reference the same copy of it, then use the <code>npm link</code> command.
That's what it's for. Install it globally, then link it into each
That's what it's for. Install it globally, then link it into each
program that uses it.</p>
<h2id="Whatever-I-really-want-the-old-style-everything-global-style">Whatever, I really want the old style 'everything global' style.</h2>
<h2id="Whatever-I-really-want-the-old-style-everything-global-style">Whatever, I really want the old style 'everything global' style.</h2>
<p>Write your own package manager, then. It's not that hard.</p>
<p>Write your own package manager, then. It's not that hard.</p>
<p>npm will not help you do something that is known to be a bad idea.</p>
<h2id="Should-I-check-my-node_modules-folder-into-git">Should I check my `node_modules` folder into git?</h2>
<h2id="Should-I-check-my-node_modules-folder-into-git">Should I check my <code>node_modules</code> folder into git?</h2>
<p>Mikeal Rogers answered this question very well:</p>
@ -91,33 +91,33 @@ websites and apps.</li><li>Do not check <code>node_modules</code> into git for l
intended to be reused.</li><li>Use npm to manage dependencies in your dev environment, but not in
your deployment scripts.</li></ul>
<h2id="Is-it-npm-or-NPM-or-Npm">Is it 'npm' or 'NPM' or 'Npm'?</h2>
<h2id="Is-it-npm-or-NPM-or-Npm">Is it 'npm' or 'NPM' or 'Npm'?</h2>
<p>npm should never be capitalized unless it is being displayed in a
location that is customarily all-caps (such as the title of man pages.)</p>
<h2id="If-npm-is-an-acronym-why-is-it-never-capitalized">If 'npm' is an acronym, why is it never capitalized?</h2>
<h2id="If-npm-is-an-acronym-why-is-it-never-capitalized">If 'npm' is an acronym, why is it never capitalized?</h2>
<p>Contrary to the belief of many, "npm" is not in fact an abbreviation for
"Node Package Manager". It is a recursive bacronymic abbreviation for
"npm is not an acronym". (If it was "ninaa", then it would be an
<p>Contrary to the belief of many, "npm" is not in fact an abbreviation for
"Node Package Manager". It is a recursive bacronymic abbreviation for
"npm is not an acronym". (If it was "ninaa", then it would be an
acronym, and thus incorrectly named.)</p>
<p>"NPM", however, <em>is</em> an acronym (more precisely, a capitonym) for the
<p>"NPM", however, <em>is</em> an acronym (more precisely, a capitonym) for the
National Association of Pastoral Musicians. You can learn more
about them at <ahref="http://npm.org/">http://npm.org/</a>.</p>
<p>In software, "NPM" is a Non-Parametric Mapping utility written by
<p>In software, "NPM" is a Non-Parametric Mapping utility written by
Chris Rorden. You can analyze pictures of brains with it. Learn more
about the (capitalized) NPM program at <ahref="http://www.cabiatl.com/mricro/npm/">http://www.cabiatl.com/mricro/npm/</a>.</p>
<p>The first seed that eventually grew into this flower was a bash utility
named "pm", which was a shortened descendent of "pkgmakeinst", a
named "pm", which was a shortened descendent of "pkgmakeinst", a
bash function that was used to install various different things on different
platforms, most often using Yahoo's <code>yinst</code>. If <code>npm</code> was ever an
platforms, most often using Yahoo's <code>yinst</code>. If <code>npm</code> was ever an
acronym for anything, it was <code>node pm</code> or maybe <code>new pm</code>.</p>
<p>So, in all seriousness, the "npm" project is named after its command-line
<p>So, in all seriousness, the "npm" project is named after its command-line
utility, which was organically selected to be easily typed by a right-handed
programmer using a US QWERTY keyboard layout, ending with the
right-ring-finger in a postition to type the <code>-</code> key for flags and
<h2id="What-is-a-package">What is a `package`?</h2>
<h2id="What-is-a-package">What is a <code>package</code>?</h2>
<p>A package is:</p>
<ul><li>a) a folder containing a program described by a package.json file</li><li>b) a gzipped tarball containing (a)</li><li>c) a url that resolves to (b)</li><li>d) a <code><name>@<version></code> that is published on the registry with (c)</li><li>e) a <code><name>@<tag></code> that points to (d)</li><li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li><li>g) a <code>git</code> url that, when cloned, results in (a).</li></ul>
<ul><li>a) a folder containing a program described by a package.json file</li><li>b) a gzipped tarball containing (a)</li><li>c) a url that resolves to (b)</li><li>d) a <code><name>@<version></code> that is published on the registry with (c)</li><li>e) a <code><name>@<tag></code> that points to (d)</li><li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li><li>g) a <code>git</code> url that, when cloned, results in (a).</li></ul>
<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
@ -173,7 +173,7 @@ an argument to <code>git checkout</code>. The default is <code>master</code>.</
<h2id="How-do-I-install-node-with-npm">How do I install node with npm?</h2>
@ -181,7 +181,7 @@ an argument to <code>git checkout</code>. The default is <code>master</code>.</
<p>See <code><ahref="../doc/developers.html">developers(1)</a></code> and <code><ahref="../doc/json.html">json(1)</a></code>.</p>
<p>You'll most likely want to <code>npm link</code> your development folder. That's
<p>You'll most likely want to <code>npm link</code> your development folder. That's
awesomely handy.</p>
<p>To set up your own private registry, check out <code><ahref="../doc/registry.html">registry(1)</a></code>.</p>
@ -190,9 +190,9 @@ awesomely handy.</p>
<p>Yes. It should be a url to a gzipped tarball containing a single folder
that has a package.json in its root, or a git url.
(See "what is a package?" above.)</p>
(See "what is a package?" above.)</p>
<h2id="How-do-I-symlink-to-a-dev-folder-so-I-don-t-have-to-keep-re-installing">How do I symlink to a dev folder so I don't have to keep re-installing?</h2>
<h2id="How-do-I-symlink-to-a-dev-folder-so-I-don-t-have-to-keep-re-installing">How do I symlink to a dev folder so I don't have to keep re-installing?</h2>
<p>npm puts various things on your computer. That's its job.</p>
<p>npm puts various things on your computer. That's its job.</p>
<p>This document will tell you what it puts where.</p>
@ -18,16 +18,16 @@
<ul><li>Local install (default): puts stuff in <code>./node_modules</code> of the current
package root.</li><li>Global install (with <code>-g</code>): puts stuff in /usr/local or wherever node
is installed.</li><li>Install it <strong>locally</strong> if you're going to <code>require()</code> it.</li><li>Install it <strong>globally</strong> if you're going to run it on the command line.</li><li>If you need both, then install it in both places, or use <code>npm link</code>.</li></ul>
is installed.</li><li>Install it <strong>locally</strong> if you're going to <code>require()</code> it.</li><li>Install it <strong>globally</strong> if you're going to run it on the command line.</li><li>If you need both, then install it in both places, or use <code>npm link</code>.</li></ul>
@ -28,7 +28,7 @@ by that. See <a href="../doc/shrinkwrap.html">shrinkwrap(1)</a>.</p>
<p>A <code>package</code> is:</p>
<ul><li>a) a folder containing a program described by a package.json file</li><li>b) a gzipped tarball containing (a)</li><li>c) a url that resolves to (b)</li><li>d) a <code><name>@<version></code> that is published on the registry with (c)</li><li>e) a <code><name>@<tag></code> that points to (d)</li><li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li><li>g) a <code><git remote url></code> that resolves to (b)</li></ul>
<ul><li>a) a folder containing a program described by a package.json file</li><li>b) a gzipped tarball containing (a)</li><li>c) a url that resolves to (b)</li><li>d) a <code><name>@<version></code> that is published on the registry with (c)</li><li>e) a <code><name>@<tag></code> that points to (d)</li><li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li><li>g) a <code><git remote url></code> that resolves to (b)</li></ul>
<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
@ -40,7 +40,7 @@ it installs the current package context (ie, the current working
directory) as a global package.</p></li><li><p><code>npm install <folder></code>:</p><p>Install a package that is sitting in a folder on the filesystem.</p></li><li><p><code>npm install <tarball file></code>:</p><p>Install a package that is sitting on the filesystem. Note: if you just want
to link a dev directory into your npm root, you can do this more easily by
using <code>npm link</code>.</p><p>Example:</p><pre><code> npm install ./package.tgz</code></pre></li><li><p><code>npm install <tarball url></code>:</p><p>Fetch the tarball url, and then install it. In order to distinguish between
this and other options, the argument must start with "http://" or "https://"</p><p>Example:</p><pre><code> npm install https://github.com/indexzero/forever/tarball/v0.5.6</code></pre></li><li><p><code>npm install <name> [--save|--save-dev|--save-optional]</code>:</p><p>Do a <code><name>@<tag></code> install, where <code><tag></code> is the "tag" config. (See
this and other options, the argument must start with "http://" or "https://"</p><p>Example:</p><pre><code> npm install https://github.com/indexzero/forever/tarball/v0.5.6</code></pre></li><li><p><code>npm install <name> [--save|--save-dev|--save-optional]</code>:</p><p>Do a <code><name>@<tag></code> install, where <code><tag></code> is the "tag" config. (See
<code><ahref="../doc/config.html">config(1)</a></code>.)</p><p>In most cases, this will install the latest version
of the module published on npm.</p><p>Example:</p><p> npm install sax</p><p><code>npm install</code> takes 3 exclusive, optional flags which save or update
the package version in your main package.json:</p><ul><li><p><code>--save</code>: Package will appear in your <code>dependencies</code>.</p></li><li><p><code>--save-dev</code>: Package will appear in your <code>devDependencies</code>.</p></li><li><p><code>--save-optional</code>: Package will appear in your <code>optionalDependencies</code>.</p><p>Examples:</p><p> npm install sax --save
@ -52,7 +52,7 @@ If the tag does not exist in the registry data for that package, then this
will fail.</p><p>Example:</p><pre><code> npm install sax@latest</code></pre></li><li><p><code>npm install <name>@<version></code>:</p><p>Install the specified version of the package. This will fail if the version
has not been published to the registry.</p><p>Example:</p><pre><code> npm install sax@0.1.1</code></pre></li><li><p><code>npm install <name>@<version range></code>:</p><p>Install a version of the package matching the specified version range. This
will follow the same rules for resolving dependencies described in <code><ahref="../doc/json.html">json(1)</a></code>.</p><p>Note that most version ranges must be put in quotes so that your shell will
treat it as a single argument.</p><p>Example:</p><p> npm install sax@">=0.1.0 <0.2.0"</p></li><li><p><code>npm install <git remote url></code>:</p><p>Install a package by cloning a git remote url. The format of the git
treat it as a single argument.</p><p>Example:</p><p> npm install sax@">=0.1.0 <0.2.0"</p></li><li><p><code>npm install <git remote url></code>:</p><p>Install a package by cloning a git remote url. The format of the git
url is:</p><p><protocol>://[<user>@]<hostname><separator><path>[#<commit-ish>]</p><p><code><protocol></code> is one of <code>git</code>, <code>git+ssh</code>, <code>git+http</code>, or
<code>git+https</code>. If no <code><commit-ish></code> is specified, then <code>master</code> is
<h1><ahref="../doc/json.html">json</a></h1><p>Specifics of npm's package.json handling</p>
<h1><ahref="../doc/json.html">json</a></h1><p>Specifics of npm's package.json handling</p>
<h2id="DESCRIPTION">DESCRIPTION</h2>
<p>This document is all you need to know about what's required in your package.json
<p>This document is all you need to know about what's required in your package.json
file. It must be actual JSON, not just a JavaScript object literal.</p>
<p>A lot of the behavior described in this document is affected by the config
@ -20,9 +20,10 @@ settings described in <code><a href="../doc/config.html">config(1)</a></code>.</
<p>npm will default some values based on package contents.</p>
<ul><li><p><code>"scripts": {"start": "node server.js"}</code></p><p>If there is a <code>server.js</code> file in the root of your package, then npm
will default the <code>start</code> command to <code>node server.js</code>.</p></li><li><p><code>"scripts":{"preinstall": "node-waf clean || true; node-waf configure build"}</code></p><p>If there is a <code>wscript</code> file in the root of your package, npm will
default the <code>preinstall</code> command to compile using node-waf.</p></li><li><p><code>"contributors": [...]</code></p><p>If there is an <code>AUTHORS</code> file in the root of your package, npm will
<ul><li><p><code>"scripts": {"start": "node server.js"}</code></p><p>If there is a <code>server.js</code> file in the root of your package, then npm
will default the <code>start</code> command to <code>node server.js</code>.</p></li><li><p><code>"scripts":{"preinstall": "node-waf clean || true; node-waf configure build"}</code></p><p>If there is a <code>wscript</code> file in the root of your package, npm will
default the <code>preinstall</code> command to compile using node-waf.</p></li><li><p><code>"scripts":{"preinstall": "node-gyp rebuild"}</code></p><p>If there is a <code>binding.gyp</code> file in the root of your package, npm will
default the <code>preinstall</code> command to compile using node-gyp.</p></li><li><p><code>"contributors": [...]</code></p><p>If there is an <code>AUTHORS</code> file in the root of your package, npm will
treat each line as a <code>Name <email> (url)</code> format, where email and url
are optional. Lines which start with a <code>#</code> or are blank, will be
ignored.</p></li></ul>
@ -30,25 +31,25 @@ ignored.</p></li></ul>
<h2id="name">name</h2>
<p>The <em>most</em> important things in your package.json are the name and version fields.
Those are actually required, and your package won't install without
Those are actually required, and your package won't install without
them. The name and version together form an identifier that is assumed
to be completely unique. Changes to the package should come along with
changes to the version.</p>
<p>The name is what your thing is called. Some tips:</p>
<ul><li>Don't put "js" or "node" in the name. It's assumed that it's js, since you're
writing a package.json file, and you can specify the engine using the "engines"
<ul><li>Don't put "js" or "node" in the name. It's assumed that it's js, since you're
writing a package.json file, and you can specify the engine using the "engines"
field. (See below.)</li><li>The name ends up being part of a URL, an argument on the command line, and a
folder name. Any name with non-url-safe characters will be rejected.
Also, it can't start with a dot or an underscore.</li><li>The name will probably be passed as an argument to require(), so it should
be something short, but also reasonably descriptive.</li><li>You may want to check the npm registry to see if there's something by that name
Also, it can't start with a dot or an underscore.</li><li>The name will probably be passed as an argument to require(), so it should
be something short, but also reasonably descriptive.</li><li>You may want to check the npm registry to see if there's something by that name
already, before you get too attached to it. http://registry.npmjs.org/</li></ul>
<h2id="version">version</h2>
<p>The <em>most</em> important things in your package.json are the name and version fields.
Those are actually required, and your package won't install without
Those are actually required, and your package won't install without
them. The name and version together form an identifier that is assumed
to be completely unique. Changes to the package should come along with
changes to the version.</p>
@ -57,89 +58,89 @@ changes to the version.</p>
<ahref="https://github.com/isaacs/node-semver">node-semver</a>, which is bundled
with npm as a dependency. (<code>npm install semver</code> to use it yourself.)</p>
<p>Here's how npm's semver implementation deviates from what's on semver.org:</p>
<p>Here's how npm's semver implementation deviates from what's on semver.org:</p>
<ul><li>Versions can start with "v"</li><li>A numeric item separated from the main three-number version by a hyphen
will be interpreted as a "build" number, and will <em>increase</em> the version.
But, if the tag is not a number separated by a hyphen, then it's treated
<ul><li>Versions can start with "v"</li><li>A numeric item separated from the main three-number version by a hyphen
will be interpreted as a "build" number, and will <em>increase</em> the version.
But, if the tag is not a number separated by a hyphen, then it's treated
as a pre-release tag, and is <em>less than</em> the version without a tag.
So, <code>0.1.2-7 > 0.1.2-7-beta > 0.1.2-6 > 0.1.2 > 0.1.2beta</code></li></ul>
<p>This is a little bit confusing to explain, but matches what you see in practice
when people create tags in git like "v1.2.3" and then do "git describe" to generate
when people create tags in git like "v1.2.3" and then do "git describe" to generate
a patch version.</p>
<h2id="description">description</h2>
<p>Put a description in it. It's a string. This helps people discover your
package, as it's listed in <code>npm search</code>.</p>
<p>Put a description in it. It's a string. This helps people discover your
package, as it's listed in <code>npm search</code>.</p>
<h2id="keywords">keywords</h2>
<p>Put keywords in it. It's an array of strings. This helps people
discover your package as it's listed in <code>npm search</code>.</p>
<p>Put keywords in it. It's an array of strings. This helps people
discover your package as it's listed in <code>npm search</code>.</p>
<h2id="homepage">homepage</h2>
<p>The url to the project homepage.</p>
<p><strong>NOTE</strong>: This is <em>not</em> the same as "url". If you put a "url" field,
then the registry will think it's a redirection to your package that has
<p><strong>NOTE</strong>: This is <em>not</em> the same as "url". If you put a "url" field,
then the registry will think it's a redirection to your package that has
been published somewhere else, and spit at you.</p>
<p>Literally. Spit. I'm so not kidding.</p>
<p>Literally. Spit. I'm so not kidding.</p>
<h2id="bugs">bugs</h2>
<p>The url to your project's issue tracker and / or the email address to which
<p>The url to your project's issue tracker and / or the email address to which
issues should be reported. These are helpful for people who encounter issues
<p>and then had a "start" command that then referenced the
<p>and then had a "start" command that then referenced the
<code>npm_package_config_port</code> environment variable, then the user could
override that by doing <code>npm config set foo:port 8001</code>.</p>
@ -303,29 +304,29 @@ configs.</p>
<p>Dependencies are specified with a simple hash of package name to version
range. The version range is EITHER a string which has one or more
space-separated descriptors, OR a range like "fromVersion - toVersion"</p>
space-separated descriptors, OR a range like "fromVersion - toVersion"</p>
<p><strong>Please do not put test harnesses in your <code>dependencies</code> hash.</strong> See
<code>devDependencies</code>, below.</p>
<p>Version range descriptors may be any of the following styles, where "version"
<p>Version range descriptors may be any of the following styles, where "version"
is a semver compatible version identifier.</p>
<ul><li><code>version</code> Must match <code>version</code> exactly</li><li><code>=version</code> Same as just <code>version</code></li><li><code>>version</code> Must be greater than <code>version</code></li><li><code>>=version</code> etc</li><li><code><version</code></li><li><code><=version</code></li><li><code>~version</code> See 'Tilde Version Ranges' below</li><li><code>1.2.x</code> See 'X Version Ranges' below</li><li><code>http://...</code> See 'URLs as Dependencies' below</li><li><code>*</code> Matches any version</li><li><code>""</code> (just an empty string) Same as <code>*</code></li><li><code>version1 - version2</code> Same as <code>>=version1 <=version2</code>.</li><li><code>range1 || range2</code> Passes if either range1 or range2 are satisfied.</li><li><code>git...</code> See 'Git URLs as Dependencies' below</li></ul>
<ul><li><code>version</code> Must match <code>version</code> exactly</li><li><code>=version</code> Same as just <code>version</code></li><li><code>>version</code> Must be greater than <code>version</code></li><li><code>>=version</code> etc</li><li><code><version</code></li><li><code><=version</code></li><li><code>~version</code> See 'Tilde Version Ranges' below</li><li><code>1.2.x</code> See 'X Version Ranges' below</li><li><code>http://...</code> See 'URLs as Dependencies' below</li><li><code>*</code> Matches any version</li><li><code>""</code> (just an empty string) Same as <code>*</code></li><li><code>version1 - version2</code> Same as <code>>=version1 <=version2</code>.</li><li><code>range1 || range2</code> Passes if either range1 or range2 are satisfied.</li><li><code>git...</code> See 'Git URLs as Dependencies' below</li></ul>
<p>You probably got npm because you want to install stuff.</p>
<p>Use <code>npm install blerg</code> to install the latest version of "blerg". Check out
<p>Use <code>npm install blerg</code> to install the latest version of "blerg". Check out
<code><ahref="../doc/install.html">install(1)</a></code> for more info. It can do a lot of stuff.</p>
<p>Use the <code>npm search</code> command to show everything that's available.
Use <code>npm ls</code> to show everything you've installed.</p>
<p>Use the <code>npm search</code> command to show everything that's available.
Use <code>npm ls</code> to show everything you've installed.</p>
<h2id="DIRECTORIES">DIRECTORIES</h2>
@ -54,15 +54,15 @@ operate in global mode instead.</p>
<h2id="DEVELOPER-USAGE">DEVELOPER USAGE</h2>
<p>If you're using npm to develop and publish your code, check out the
<p>If you're using npm to develop and publish your code, check out the
following help topics:</p>
<ul><li>json:
Make a package.json file. See <code><ahref="../doc/json.html">json(1)</a></code>.</li><li>link:
For linking your current working code into Node's path, so that you
don't have to reinstall every time you make a change. Use
For linking your current working code into Node's path, so that you
don't have to reinstall every time you make a change. Use
<code>npm link</code> to do this.</li><li>install:
It's a good idea to install things if you don't need the symbolic link.
It's a good idea to install things if you don't need the symbolic link.
Especially, installing other peoples code from the registry is done via
<code>npm install</code></li><li>adduser:
Create an account or log in. Credentials are stored in the
@ -75,7 +75,7 @@ Use the <code>npm publish</code> command to upload your code to the registry.</l
5 places.</p>
<ul><li>Command line switches:<br/>Set a config with <code>--key val</code>. All keys take a value, even if they
are booleans (the config parser doesn't know what the options are at
are booleans (the config parser doesn't know what the options are at
the time of parsing.) If no value is provided, then the option is set
to boolean <code>true</code>.</li><li>Environment Variables:<br/>Set any config by prefixing the name in an environment variable with
<code>npm_config_</code>. For example, <code>export npm_config_key=val</code>.</li><li>User Configs:<br/>The file at $HOME/.npmrc is an ini-formatted list of configs. If
@ -83,7 +83,7 @@ present, it is parsed. If the <code>userconfig</code> option is set in the cli
or env, then that will be used instead.</li><li>Global Configs:<br/>The file found at ../etc/npmrc (from the node executable, by default
this resolves to /usr/local/etc/npmrc) will be parsed if it is found.
If the <code>globalconfig</code> option is set in the cli, env, or user config,
then that file is parsed instead.</li><li>Defaults:<br/>npm's default configuration options are defined in
then that file is parsed instead.</li><li>Defaults:<br/>npm's default configuration options are defined in
lib/utils/config-defs.js. These must not be changed.</li></ul>
<p>See <code><ahref="../doc/config.html">config(1)</a></code> for much much more information.</p>
@ -94,14 +94,14 @@ lib/utils/config-defs.js. These must not be changed.</li></ul>
<ul><li>code:
Read through <code><ahref="../doc/coding-style.html">coding-style(1)</a></code> if you plan to submit code.
You don't have to agree with it, but you do have to follow it.</li><li>docs:
You don't have to agree with it, but you do have to follow it.</li><li>docs:
If you find an error in the documentation, edit the appropriate markdown
file in the "doc" folder. (Don't worry about generating the man page.)</li></ul>
file in the "doc" folder. (Don't worry about generating the man page.)</li></ul>
<p>Contributors are listed in npm's <code>package.json</code> file. You can view them
<p>Contributors are listed in npm's <code>package.json</code> file. You can view them
easily by doing <code>npm view npm contributors</code>.</p>
<p>If you would like to contribute, but don't know what to work on, check
<p>If you would like to contribute, but don't know what to work on, check
that implements the CommonJS Package Registry specification for reading
package info.</p>
<p>Additionally, npm's package registry implementation supports several
<p>Additionally, npm's package registry implementation supports several
write APIs as well, to allow for publishing packages and managing user
account information.</p>
@ -26,7 +26,7 @@ are CouchDB users, stored in the <a href="http://isaacs.iriscouch.com/_users">ht
database.</p>
<p>The registry URL is supplied by the <code>registry</code> config parameter. See
<code><ahref="../doc/config.html">config(1)</a></code> for more on managing npm's configuration.</p>
<code><ahref="../doc/config.html">config(1)</a></code> for more on managing npm's configuration.</p>
<h2id="Can-I-run-my-own-private-registry">Can I run my own private registry?</h2>
@ -36,17 +36,17 @@ database.</p>
similar) design doc to implement the APIs.</p>
<p>If you set up continuous replication from the official CouchDB, and then
set your internal CouchDB as the registry config, then you'll be able
set your internal CouchDB as the registry config, then you'll be able
to read any published packages, in addition to your private ones, and by
default will only publish internally. If you then want to publish a
package for the whole world to see, you can simply override the
<code>--registry</code> config for that command.</p>
<h2id="I-don-t-want-my-package-published-in-the-official-registry-It-s-private">I don't want my package published in the official registry. It's private.</h2>
<h2id="I-don-t-want-my-package-published-in-the-official-registry-It-s-private">I don't want my package published in the official registry. It's private.</h2>
<p>Set <code>"private": true</code> in your package.json to prevent it from being
<p>Set <code>"private": true</code> in your package.json to prevent it from being
to force it to be published only to your internal registry.</p>
<p>See <code><ahref="../doc/json.html">json(1)</a></code> for more info on what goes in the package.json file.</p>
@ -59,11 +59,11 @@ otherwise.</p>
<h2id="Do-I-have-to-use-couchdb-to-build-a-registry-that-npm-can-talk-to">Do I have to use couchdb to build a registry that npm can talk to?</h2>
<p>No, but it's way easier.</p>
<p>No, but it's way easier.</p>
<h2id="I-published-something-elsewhere-and-want-to-tell-the-npm-registry-about-it">I published something elsewhere, and want to tell the npm registry about it.</h2>
<p>That is supported, but not using the npm client. You'll have to get
<p>That is supported, but not using the npm client. You'll have to get
your hands dirty and do some HTTP. The request looks something like
this:</p>
@ -72,19 +72,19 @@ content-type:application/json
accept:application/json
authorization:Basic $base_64_encoded
{ "name":"my-foreign-package"
, "maintainers":["owner","usernames"]
, "description":"A package that is hosted elsewhere"
<h1><ahref="../doc/scripts.html">scripts</a></h1><p>How npm handles the "scripts" field</p>
<h1><ahref="../doc/scripts.html">scripts</a></h1><p>How npm handles the "scripts" field</p>
<h2id="DESCRIPTION">DESCRIPTION</h2>
<p>npm supports the "scripts" member of the package.json script, for the
<p>npm supports the "scripts" member of the package.json script, for the
following scripts:</p>
<ul><li>preinstall:
@ -35,8 +35,8 @@ stop and start scripts if no <code>restart</code> script is provided.</li></ul>
<p>npm will default some script values based on package contents.</p>
<ul><li><p><code>"start": "node server.js"</code>:</p><p>If there is a <code>server.js</code> file in the root of your package, then npm
will default the <code>start</code> command to <code>node server.js</code>.</p></li><li><p><code>"preinstall": "node-waf clean || true; node-waf configure build"</code>:</p><p>If there is a <code>wscript</code> file in the root of your package, npm will
<ul><li><p><code>"start": "node server.js"</code>:</p><p>If there is a <code>server.js</code> file in the root of your package, then npm
will default the <code>start</code> command to <code>node server.js</code>.</p></li><li><p><code>"preinstall": "node-waf clean || true; node-waf configure build"</code>:</p><p>If there is a <code>wscript</code> file in the root of your package, npm will
default the <code>preinstall</code> command to compile using node-waf.</p></li></ul>
<h2id="USER">USER</h2>
@ -58,9 +58,9 @@ process.</p>
then those executables will be added to the <code>PATH</code> for executing the scripts.
@ -52,7 +52,7 @@ multiple versions to the utility will just sort them.</code></pre>
<ul><li>a number (Major)</li><li>a period</li><li>a number (minor)</li><li>a period</li><li>a number (patch)</li><li>OPTIONAL: a hyphen, followed by a number (build)</li><li>OPTIONAL: a collection of pretty much any non-whitespace characters
(tag)</li></ul>
<p>A leading <code>"="</code> or <code>"v"</code> character is stripped off and ignored.</p>
<p>A leading <code>"="</code> or <code>"v"</code> character is stripped off and ignored.</p>
<h2id="Comparisons">Comparisons</h2>
@ -67,7 +67,7 @@ build number. <code>2.3.4-0 > 2.3.4</code></li><li>If they both have build n
different, then take the one with the bigger build number.
<code>2.3.4-10 > 2.3.4-9</code></li><li>If only one of them has a tag, then take the one without the tag.
<code>2.3.4 > 2.3.4-beta</code></li><li>If they both have tags, then take the one with the lexicographically
larger tag. <code>2.3.4-beta > 2.3.4-alpha</code></li><li>At this point, they're equal.</li></ul>
larger tag. <code>2.3.4-beta > 2.3.4-alpha</code></li><li>At this point, they're equal.</li></ul>
<h2id="Ranges">Ranges</h2>
@ -75,20 +75,20 @@ larger tag. <code>2.3.4-beta > 2.3.4-alpha</code></li><li>At this point, the
<ul><li><code>>1.2.3</code> Greater than a specific version.</li><li><code><1.2.3</code> Less than</li><li><code>1.2.3 - 2.3.4</code> := <code>>=1.2.3 <=2.3.4</code></li><li><code>~1.2.3</code> := <code>>=1.2.3 <1.3.0</code></li><li><code>~1.2</code> := <code>>=1.2.0 <2.0.0</code></li><li><code>~1</code> := <code>>=1.0.0 <2.0.0</code></li><li><code>1.2.x</code> := <code>>=1.2.0 <1.3.0</code></li><li><code>1.x</code> := <code>>=1.0.0 <2.0.0</code></li></ul>
<p>Ranges can be joined with either a space (which implies "and") or a
<code>||</code> (which implies "or").</p>
<p>Ranges can be joined with either a space (which implies "and") or a
<ul><li>valid(v): Return the parsed version, or null if it's not valid.</li><li>inc(v, release): Return the version incremented by the release type
(major, minor, patch, or build), or null if it's not valid.</li></ul>
<ul><li>valid(v): Return the parsed version, or null if it's not valid.</li><li>inc(v, release): Return the version incremented by the release type
(major, minor, patch, or build), or null if it's not valid.</li></ul>
<h3id="Comparison">Comparison</h3>
<ul><li>gt(v1, v2): <code>v1 > v2</code></li><li>gte(v1, v2): <code>v1 >= v2</code></li><li>lt(v1, v2): <code>v1 < v2</code></li><li>lte(v1, v2): <code>v1 <= v2</code></li><li>eq(v1, v2): <code>v1 == v2</code> This is true if they're logically equivalent,
even if they're not the exact same string. You already know how to
compare strings.</li><li>neq(v1, v2): <code>v1 != v2</code> The opposite of eq.</li><li>cmp(v1, comparator, v2): Pass in a comparison string, and it'll call
the corresponding function above. <code>"==="</code> and <code>"!=="</code> do simple
<ul><li>gt(v1, v2): <code>v1 > v2</code></li><li>gte(v1, v2): <code>v1 >= v2</code></li><li>lt(v1, v2): <code>v1 < v2</code></li><li>lte(v1, v2): <code>v1 <= v2</code></li><li>eq(v1, v2): <code>v1 == v2</code> This is true if they're logically equivalent,
even if they're not the exact same string. You already know how to
compare strings.</li><li>neq(v1, v2): <code>v1 != v2</code> The opposite of eq.</li><li>cmp(v1, comparator, v2): Pass in a comparison string, and it'll call
the corresponding function above. <code>"==="</code> and <code>"!=="</code> do simple
string comparison, but are included for completeness. Throws if an
invalid comparison string is provided.</li><li>compare(v1, v2): Return 0 if v1 == v2, or 1 if v1 is greater, or -1 if
v2 is greater. Sorts in ascending order if passed to Array.sort().</li><li>rcompare(v1, v2): The reverse of compare. Sorts an array of versions
@ -96,7 +96,7 @@ in descending order when passed to Array.sort().</li></ul>
<h3id="Ranges">Ranges</h3>
<ul><li>validRange(range): Return the valid range or null if it's not valid</li><li>satisfies(version, range): Return true if the version satisfies the
<ul><li>validRange(range): Return the valid range or null if it's not valid</li><li>satisfies(version, range): Return true if the version satisfies the
range.</li><li>maxSatisfying(versions, range): Return the highest version in the list
that satisfies the range, or null if none of them do.</li></ul>
@ -104,7 +104,7 @@ that satisfies the range, or null if none of them do.</li></ul>
<ol><li>Run "npm install" in the package root to install the current versions of all
dependencies.</li><li>Validate that the package works as expected with these versions.</li><li>Run "npm shrinkwrap", add npm-shrinkwrap.json to git, and publish your
<ol><li>Run "npm install" in the package root to install the current versions of all
dependencies.</li><li>Validate that the package works as expected with these versions.</li><li>Run "npm shrinkwrap", add npm-shrinkwrap.json to git, and publish your
package.</li></ol>
<p>To add or update a dependency in a shrinkwrapped package:</p>
<ol><li>Run "npm install" in the package root to install the current versions of all
dependencies.</li><li>Add or update dependencies. "npm install" each new or updated package
<ol><li>Run "npm install" in the package root to install the current versions of all
dependencies.</li><li>Add or update dependencies. "npm install" each new or updated package
individually and then update package.json. Note that they must be
explicitly named in order to be installed: running <code>npm install</code> with
no arguments will merely reproduce the existing shrinkwrap.</li><li>Validate that the package works as expected with the new dependencies.</li><li>Run "npm shrinkwrap", commit the new npm-shrinkwrap.json, and publish your
no arguments will merely reproduce the existing shrinkwrap.</li><li>Validate that the package works as expected with the new dependencies.</li><li>Run "npm shrinkwrap", commit the new npm-shrinkwrap.json, and publish your
package.</li></ol>
<p>You can use <ahref="../doc/outdated.html">outdated(1)</a> to view dependencies with newer versions available.</p>
<h3id="Other-Notes">Other Notes</h3>
<p>Since "npm shrinkwrap" uses the locally installed packages to construct the
shrinkwrap file, devDependencies will be included if and only if you've
<p>Since "npm shrinkwrap" uses the locally installed packages to construct the
shrinkwrap file, devDependencies will be included if and only if you've
installed them already when you make the shrinkwrap.</p>
<p>A shrinkwrap file must be consistent with the package's package.json file. "npm
shrinkwrap" will fail if required dependencies are not already installed, since
that would result in a shrinkwrap that wouldn't actually work. Similarly, the
<p>A shrinkwrap file must be consistent with the package's package.json file. "npm
shrinkwrap" will fail if required dependencies are not already installed, since
that would result in a shrinkwrap that wouldn't actually work. Similarly, the
command will fail if there are extraneous packages (not referenced by
package.json), since that would indicate that package.json is not correct.</p>
<p>If shrinkwrapped package A depends on shrinkwrapped package B, B's shrinkwrap
will not be used as part of the installation of A. However, because A's
<p>If shrinkwrapped package A depends on shrinkwrapped package B, B's shrinkwrap
will not be used as part of the installation of A. However, because A's
shrinkwrap is constructed from a valid installation of B and recursively
specifies all dependencies, the contents of B's shrinkwrap will implicitly be
included in A's shrinkwrap.</p>
specifies all dependencies, the contents of B's shrinkwrap will implicitly be
included in A's shrinkwrap.</p>
<h3id="Caveats">Caveats</h3>
@ -155,7 +155,7 @@ included in A's shrinkwrap.</p>
While discouraged, a package author can republish an existing version of a
package, causing shrinkwrapped packages using that version to pick up different
code than they were before. If you want to avoid any risk that a byzantine
author replaces a package you're using with code that breaks your application,
author replaces a package you're using with code that breaks your application,
you could modify the shrinkwrap file to use git URL references rather than
version numbers so that npm always fetches all packages from git.</p>
Ben Noordhuis
13 years ago