* Don't set referer if already set
* fetch: Send referer and npm-session headers
* run-script: Support --parseable and --json
* list runnable scripts (Evan Lucas)
* Use marked instead of ronn for html docs
<p>Get the code with git. Use <code>make</code> to build the docs and do other stuff.
<p>Get the code with git. Use <code>make</code> to build the docs and do other stuff.
If you plan on hacking on npm, <code>make link</code> is your friend.</p>
If you plan on hacking on npm, <code>make link</code> is your friend.</p>
<p>If you've got the npm source code, you can also semi-permanently set
<p>If you've got the npm source code, you can also semi-permanently set
arbitrary config keys using the <code>./configure --key=val ...</code>, and then
arbitrary config keys using the <code>./configure --key=val ...</code>, and then
run npm commands by doing <code>node cli.js <cmd><args></code>. (This is helpful
run npm commands by doing <code>node cli.js <cmd><args></code>. (This is helpful
for testing, or running stuff without actually installing npm itself.)</p>
for testing, or running stuff without actually installing npm itself.)</p>
<h2id="fancy-windows-install">Fancy Windows Install</h2>
<h2id="Fancy-Windows-Install">Fancy Windows Install</h2>
<p>You can download a zip file from <ahref="https://npmjs.org/dist/">https://npmjs.org/dist/</a>, and unpack it
<p>You can download a zip file from <ahref="https://npmjs.org/dist/">https://npmjs.org/dist/</a>, and unpack it
in the same folder where node.exe lives.</p>
in the same folder where node.exe lives.</p>
<p>If that's not fancy enough for you, then you can fetch the code with
<p>If that's not fancy enough for you, then you can fetch the code with
git, and mess with it directly.</p>
git, and mess with it directly.</p>
<h2id="installing-on-cygwin">Installing on Cygwin</h2>
<h2id="Installing-on-Cygwin">Installing on Cygwin</h2>
<p>No.</p>
<p>No.</p>
<h2id="permissions-when-using-npm-to-install-other-stuff">Permissions when Using npm to Install Other Stuff</h2>
<h2id="Permissions-when-Using-npm-to-Install-Other-Stuff">Permissions when Using npm to Install Other Stuff</h2>
<p><strong>tl;dr</strong></p>
<p><strong>tl;dr</strong></p>
<ul>
<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
<li>Use <code>sudo</code> for greater safety. Or don't, if you prefer not to.</li>
scripts that package authors specified.</li></ul>
<li>npm will downgrade permissions if it's root before running any build
scripts that package authors specified.</li>
<h3id="More-details">More details...</h3>
</ul>
<h3id="more-details-">More details...</h3>
<p>As of version 0.3, it is recommended to run npm as root.
<p>As of version 0.3, it is recommended to run npm as root.
This allows npm to change the user identifier to the <code>nobody</code> user prior
This allows npm to change the user identifier to the <code>nobody</code> user prior
to running any package build or test commands.</p>
to running any package build or test commands.</p>
<p>If you are not the root user, or if you are on a platform that does not
<p>If you are not the root user, or if you are on a platform that does not
support uid switching, then npm will not attempt to change the userid.</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
<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>
set the following configuration param:</p>
<pre><code>npm config set unsafe-perm false
<pre><code>npm config set unsafe-perm false</code></pre>
</code></pre><p>This will prevent running in unsafe mode, even as non-root users.</p>
<h2id="uninstalling">Uninstalling</h2>
<p>This will prevent running in unsafe mode, even as non-root users.</p>
<h2id="Uninstalling">Uninstalling</h2>
<p>So sad to see you go.</p>
<p>So sad to see you go.</p>
<pre><code>sudo npm uninstall npm -g
<pre><code>sudo npm uninstall npm -g</code></pre>
</code></pre><p>Or, if that fails,</p>
<pre><code>sudo make uninstall
<p>Or, if that fails,</p>
</code></pre><h2id="more-severe-uninstalling">More Severe Uninstalling</h2>
<pre><code>sudo make uninstall</code></pre>
<h2id="More-Severe-Uninstalling">More Severe Uninstalling</h2>
<p>Usually, the above instructions are sufficient. That will remove
<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,
<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
then you can use the <code>npm ls</code> command to find them, and then <code>npm rm</code> to
remove them.</p>
remove them.</p>
<p>To remove cruft left behind by npm 0.x, you can use the included
<p>To remove cruft left behind by npm 0.x, you can use the included
<code>clean-old.sh</code> script file. You can run it conveniently like this:</p>
<code>clean-old.sh</code> script file. You can run it conveniently like this:</p>
<pre><code>npm explore npm -g -- sh scripts/clean-old.sh
<pre><code>npm explore npm -g -- sh scripts/clean-old.sh</code></pre>
</code></pre><p>npm uses two configuration files, one for per-user configs, and another
<p>npm uses two configuration files, one for per-user configs, and another
for global (every-user) configs. You can view them by doing:</p>
for global (every-user) configs. You can view them by doing:</p>
<pre><code>npm config get userconfig # defaults to ~/.npmrc
<pre><code>npm config get userconfig # defaults to ~/.npmrc
npm config get globalconfig # defaults to /usr/local/etc/npmrc</code></pre>
npm config get globalconfig # defaults to /usr/local/etc/npmrc
</code></pre><p>Uninstalling npm does not remove configuration files by default. You
<p>Uninstalling npm does not remove configuration files by default. You
must remove them yourself manually if you want them gone. Note that
must remove them yourself manually if you want them gone. Note that
this means that future npm installs will not remember the settings that
this means that future npm installs will not remember the settings that
<p>If you would like to use npm programmatically, you can do that.
<p>If you would like to use npm programmatically, you can do that.
It's not very well documented, but it <em>is</em> rather simple.</p>
It's not very well documented, but it <em>is</em> rather simple.</p>
<p>Most of the time, unless you actually want to do all the things that
<p>Most of the time, unless you actually want to do all the things that
npm does, you should try using one of npm's dependencies rather than
npm does, you should try using one of npm's dependencies rather than
using npm itself, if possible.</p>
using npm itself, if possible.</p>
<p>Eventually, npm will be just a thin cli wrapper around the modules
<p>Eventually, npm will be just a thin cli wrapper around the modules
that it depends on, but for now, there are some things that you must
that it depends on, but for now, there are some things that you must
use npm itself to do.</p>
use npm itself to do.</p>
<pre><code>var npm = require("npm")
<pre><code>var npm = require("npm")
npm.load(myConfigObject, function (er) {
npm.load(myConfigObject, function (er) {
if (er) return handlError(er)
if (er) return handlError(er)
@ -165,90 +109,72 @@ npm.load(myConfigObject, function (er) {
// command succeeded, and data might have some info
// command succeeded, and data might have some info
})
})
npm.on("log", function (message) { .... })
npm.on("log", function (message) { .... })
})</code></pre>
})
</code></pre><p>The <code>load</code> function takes an object hash of the command-line configs.
<p>The <code>load</code> function takes an object hash of the command-line configs.
The various <code>npm.commands.<cmd></code> functions take an <strong>array</strong> of
The various <code>npm.commands.<cmd></code> functions take an <strong>array</strong> of
positional argument <strong>strings</strong>. The last argument to any
positional argument <strong>strings</strong>. The last argument to any
<code>npm.commands.<cmd></code> function is a callback. Some commands take other
<code>npm.commands.<cmd></code> function is a callback. Some commands take other
optional arguments. Read the source.</p>
optional arguments. Read the source.</p>
<p>You cannot set configs individually for any single npm function at this
<p>You cannot set configs individually for any single npm function at this
time. Since <code>npm</code> is a singleton, any call to <code>npm.config.set</code> will
time. Since <code>npm</code> is a singleton, any call to <code>npm.config.set</code> will
change the value for <em>all</em> npm commands in that process.</p>
change the value for <em>all</em> npm commands in that process.</p>
<p>See <code>./bin/npm-cli.js</code> for an example of pulling config values off of the
<p>See <code>./bin/npm-cli.js</code> for an example of pulling config values off of the
command line arguments using nopt. You may also want to check out <code>npm
command line arguments using nopt. You may also want to check out <code>npm
help config</code> to learn about all the options you can set there.</p>
help config</code> to learn about all the options you can set there.</p>
<h2id="more-docs">More Docs</h2>
<h2id="More-Docs">More Docs</h2>
<p>Check out the <ahref="https://www.npmjs.org/doc/">docs</a>,
<p>Check out the <ahref="https://www.npmjs.org/doc/">docs</a>,
especially the <ahref="https://www.npmjs.org/doc/faq.html">faq</a>.</p>
especially the <ahref="https://www.npmjs.org/doc/faq.html">faq</a>.</p>
<p>You can use the <code>npm help</code> command to read any of them.</p>
<p>You can use the <code>npm help</code> command to read any of them.</p>
<p>If you're a developer, and you want to use npm to publish your program,
<p>If you're a developer, and you want to use npm to publish your program,
you should <ahref="https://www.npmjs.org/doc/developers.html">read this</a></p>
you should <ahref="https://www.npmjs.org/doc/developers.html">read this</a></p>
<h2id="legal-stuff">Legal Stuff</h2>
<h2id="Legal-Stuff">Legal Stuff</h2>
<p>"npm" and "The npm Registry" are owned by npm, Inc.
<p>"npm" and "The npm Registry" are owned by npm, Inc.
All rights reserved. See the included LICENSE file for more details.</p>
All rights reserved. See the included LICENSE file for more details.</p>
<p>"Node.js" and "node" are trademarks owned by Joyent, Inc.</p>
<p>"Node.js" and "node" are trademarks owned by Joyent, Inc.</p>
<p>Modules published on the npm registry are not officially endorsed by
<p>Modules published on the npm registry are not officially endorsed by
npm, Inc. or the Node.js project.</p>
npm, Inc. or the Node.js project.</p>
<p>Data published to the npm registry is not part of npm itself, and is
<p>Data published to the npm registry is not part of npm itself, and is
the sole property of the publisher. While every effort is made to
the sole property of the publisher. While every effort is made to
ensure accountability, there is absolutely no guarantee, warrantee, or
ensure accountability, there is absolutely no guarantee, warrantee, or
assertion expressed or implied as to the quality, fitness for a
assertion expressed or implied as to the quality, fitness for a
specific purpose, or lack of malice in any given npm package.</p>
specific purpose, or lack of malice in any given npm package.</p>
<p>If you have a complaint about a package in the public npm registry,
<p>If you have a complaint about a package in the public npm registry,
and cannot <ahref="https://www.npmjs.org/doc/misc/npm-disputes.html">resolve it with the package
and cannot <ahref="https://www.npmjs.org/doc/misc/npm-disputes.html">resolve it with the package
owner</a>, please email
owner</a>, please email
<ahref="mailto:support@npmjs.com">support@npmjs.com</a> and explain the situation.</p>
<ahref="mailto:support@npmjs.com">support@npmjs.com</a> and explain the situation.</p>
<p>Any data published to The npm Registry (including user account
<p>Any data published to The npm Registry (including user account
information) may be removed or modified at the sole discretion of the
information) may be removed or modified at the sole discretion of the
<h1><ahref="../api/npm-config.html">npm-config</a></h1><p>Manage the npm configuration files</p>
<h1><ahref="../api/npm-config.html">npm-config</a></h1><p>Manage the npm configuration files</p>
<h2id="synopsis">SYNOPSIS</h2>
<h2id="SYNOPSIS">SYNOPSIS</h2>
<pre><code>npm.commands.config(args, callback)
<pre><code>npm.commands.config(args, callback)
var val = npm.config.get(key)
var val = npm.config.get(key)
npm.config.set(key, val)</code></pre>
npm.config.set(key, val)
</code></pre><h2id="description">DESCRIPTION</h2>
<h2id="DESCRIPTION">DESCRIPTION</h2>
<p>This function acts much the same way as the command-line version. The first
<p>This function acts much the same way as the command-line version. The first
element in the array tells config what to do. Possible values are:</p>
element in the array tells config what to do. Possible values are:</p>
<ul>
<ul><li><p><code>set</code></p><p>Sets a config parameter. The second element in <code>args</code> is interpreted as the
<li><p><code>set</code></p>
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
<p> Sets a config parameter. The second element in <code>args</code> is interpreted as 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, and the third element is interpreted as the value.</p>
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
</li>
programmatically, but it is made available.</p></li></ul>
<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
programmatically, but it is made available.</p>
</li>
</ul>
<p>To programmatically access npm configuration settings, or set them for
<p>To programmatically access npm configuration settings, or set them for
the duration of a program, use the <code>npm.config.set</code> and <code>npm.config.get</code>
the duration of a program, use the <code>npm.config.set</code> and <code>npm.config.get</code>
<p>Spawn a subshell in the directory of the installed package specified.</p>
<p>Spawn a subshell in the directory of the installed package specified.</p>
<p>If a command is specified, then it is run in the subshell, which then
<p>If a command is specified, then it is run in the subshell, which then
immediately terminates.</p>
immediately terminates.</p>
<p>Note that the package is <em>not</em> automatically rebuilt afterwards, so be
<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>
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>
<p>Search the registry for packages matching the search terms. The available parameters are:</p>
<p>Search the registry for packages matching the search terms. The available parameters are:</p>
<ul>
<ul><li>searchTerms:
<li>searchTerms:
Array of search terms. These terms are case-insensitive.</li><li>silent:
Array of search terms. These terms are case-insensitive.</li>
If true, npm will not log anything to the console.</li><li>staleness:
<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:
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
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.
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>
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
<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
search terms. It also removes any items from the results that contain an
excluded term (the "searchexclude" config). The search is case insensitive
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
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>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>
client, see <code><ahref="../cli/npm.html">npm(1)</a></code>.</p>
client, see <code><ahref="../cli/npm.html">npm(1)</a></code>.</p>
<p>Prior to using npm's commands, <code>npm.load()</code> must be called.
<p>Prior to using npm's commands, <code>npm.load()</code> must be called.
If you provide <code>configObject</code> as an object hash of top-level
If you provide <code>configObject</code> as an object hash of top-level
configs, they override the values stored in the various config
configs, they override the values stored in the various config
@ -42,58 +35,70 @@ locations. In the npm command line client, this set of configs
is parsed from the command line options. Additional configuration
is parsed from the command line options. Additional configuration
params are loaded from two configuration files. See <code><ahref="../cli/npm-config.html">npm-config(1)</a></code>,
params are loaded from two configuration files. See <code><ahref="../cli/npm-config.html">npm-config(1)</a></code>,
<code><ahref="../misc/npm-config.html">npm-config(7)</a></code>, and <code><ahref="../files/npmrc.html">npmrc(5)</a></code> for more information.</p>
<code><ahref="../misc/npm-config.html">npm-config(7)</a></code>, and <code><ahref="../files/npmrc.html">npmrc(5)</a></code> for more information.</p>
<p>After that, each of the functions are accessible in the
<p>After that, each of the functions are accessible in the
commands object: <code>npm.commands.<cmd></code>. See <code><ahref="../misc/npm-index.html">npm-index(7)</a></code> for a list of
commands object: <code>npm.commands.<cmd></code>. See <code><ahref="../misc/npm-index.html">npm-index(7)</a></code> for a list of
all possible commands.</p>
all possible commands.</p>
<p>All commands on the command object take an <strong>array</strong> of positional argument
<p>All commands on the command object take an <strong>array</strong> of positional argument
<strong>strings</strong>. The last argument to any function is a callback. Some
<strong>strings</strong>. The last argument to any function is a callback. Some
commands take other optional arguments.</p>
commands take other optional arguments.</p>
<p>Configs cannot currently be set on a per function basis, as each call to
<p>Configs cannot currently be set on a per function basis, as each call to
npm.config.set will change the value for <em>all</em> npm commands in that process.</p>
npm.config.set will change the value for <em>all</em> npm commands in that process.</p>
<p>To find API documentation for a specific command, run the <code>npm apihelp</code>
<p>To find API documentation for a specific command, run the <code>npm apihelp</code>
command.</p>
command.</p>
<h2id="methods-and-properties">METHODS AND PROPERTIES</h2>
<h2id="METHODS-AND-PROPERTIES">METHODS AND PROPERTIES</h2>
<ul>
<li><p><code>npm.load(configs, cb)</code></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
<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
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>
directory.)</p></li><li><p><code>npm.cache</code></p><p>The place where npm keeps JSON and tarballs it fetches from the
</li>
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
<li><p><code>npm.config</code></p>
abbreviation.</p></li></ul>
<p> An object for accessing npm configuration parameters.</p>
<ul>
<h2id="MAGIC">MAGIC</h2>
<li><code>npm.config.get(key)</code></li>
<li><code>npm.config.set(key, val)</code></li>
<li><code>npm.config.del(key)</code></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
abbreviation.</p>
</li>
</ul>
<h2id="magic">MAGIC</h2>
<p>For each of the methods in the <code>npm.commands</code> hash, a method is added to
<p>For each of the methods in the <code>npm.commands</code> hash, a method is added to
the npm object, which takes a set of positional string arguments rather
the npm object, which takes a set of positional string arguments rather
than an array and a callback.</p>
than an array and a callback.</p>
<p>If the last argument is a callback, then it will use the supplied
<p>If the last argument is a callback, then it will use the supplied
callback. However, if no callback is provided, then it will print out
callback. However, if no callback is provided, then it will print out
the error or results.</p>
the error or results.</p>
<p>For example, this would work in a node repl:</p>
<p>For example, this would work in a node repl:</p>
npm i (with any of the previous argument usage)</code></pre>
npm i (with any of the previous argument usage)
</code></pre><h2id="description">DESCRIPTION</h2>
<h2id="DESCRIPTION">DESCRIPTION</h2>
<p>This command installs a package, and any packages that it depends on. If the
<p>This command installs a package, and any packages that it depends on. If the
package has a shrinkwrap file, the installation of dependencies will be driven
package has a shrinkwrap file, the installation of dependencies will be driven
by that. See <ahref="../cli/npm-shrinkwrap.html">npm-shrinkwrap(1)</a>.</p>
by that. See <ahref="../cli/npm-shrinkwrap.html">npm-shrinkwrap(1)</a>.</p>
<p>A <code>package</code> is:</p>
<p>A <code>package</code> is:</p>
<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 (see <code><ahref="../misc/npm-registry.html">npm-registry(7)</a></code>) 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>
<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 (see <code><ahref="../misc/npm-registry.html">npm-registry(7)</a></code>) 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
<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
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
perhaps if you also want to be able to easily install it elsewhere
after packing it up into a tarball (b).</p>
after packing it up into a tarball (b).</p>
<ul>
<ul><li><p><code>npm install</code> (in package directory, no arguments):</p><p>Install the dependencies in the local node_modules folder.</p><p>In global mode (ie, with <code>-g</code> or <code>--global</code> appended to the command),
<li><p><code>npm install</code> (in package directory, no arguments):</p>
it installs the current package context (ie, the current working
<p> Install the dependencies in the local node_modules folder.</p>
directory) as a global package.</p><p>By default, <code>npm install</code> will install all modules listed as
<p> In global mode (ie, with <code>-g</code> or <code>--global</code> appended to the command),
dependencies. With the <code>--production</code> flag,
it installs the current package context (ie, the current working
npm will not install modules listed in <code>devDependencies</code>.</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
directory) as a global package.</p>
to link a dev directory into your npm root, you can do this more easily by
<p> By default, <code>npm install</code> will install all modules listed as
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
dependencies. With the <code>--production</code> flag,
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
npm will not install modules listed in <code>devDependencies</code>.</p>
<code><ahref="../misc/npm-config.html">npm-config(7)</a></code>.)</p><p>In most cases, this will install the latest version
</li>
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>When using any of the above options to save dependencies to your
<p> Install a package that is sitting in a folder on the filesystem.</p>
package.json, there is an additional, optional flag:</p></li><li><p><code>--save-exact</code>: Saved dependencies will be configured with an
npm install readable-stream --save --save-exact</p><p><strong>Note</strong>: If there is a file or folder named <code><name></code> in the current
npm install node-tap --save-dev
npm install dtrace-provider --save-optional
npm install readable-stream --save --save-exact
</code></pre></li>
</ul>
</li>
</ul>
<pre><code>**Note**: If there is a file or folder named `<name>` in the current
working directory, then it will try to install that, and only try to
working directory, then it will try to install that, and only try to
fetch the package by name if it is not valid.</p></li></ul></li><li><p><code>npm install <name>@<tag></code>:</p><p>Install the version of the package that is referenced by the specified tag.
fetch the package by name if it is not valid.
If the tag does not exist in the registry data for that package, then this
</code></pre><ul>
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
<p> Install the version of the package that is referenced by the specified tag.
will follow the same rules for resolving dependencies described in <code><ahref="../files/package.json.html">package.json(5)</a></code>.</p><p>Note that most version ranges must be put in quotes so that your shell will
If the tag does not exist in the registry data for that package, then this
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
will fail.</p>
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
<p> Example:</p>
<code>git+https</code>. If no <code><commit-ish></code> is specified, then <code>master</code> is
<ol><li>Run "npm install" in the package root to install the current
<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
versions of all dependencies.</li>
your package.</li></ol>
<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>
<p>To add or update a dependency in a shrinkwrapped package:</p>
<ol>
<ol><li>Run "npm install" in the package root to install the current
<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
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
package individually and then update package.json. Note that they
must be explicitly named in order to be installed: running <code>npm
must be explicitly named in order to be installed: running <code>npm
install</code> with no arguments will merely reproduce the existing
install</code> with no arguments will merely reproduce the existing
shrinkwrap.</li><li>Validate that the package works as expected with the new
shrinkwrap.</li>
dependencies.</li><li>Run "npm shrinkwrap", commit the new npm-shrinkwrap.json, and
<li>Validate that the package works as expected with the new
publish your package.</li></ol>
dependencies.</li>
<li>Run "npm shrinkwrap", commit the new npm-shrinkwrap.json, and
publish your package.</li>
</ol>
<p>You can use <ahref="../cli/npm-outdated.html">npm-outdated(1)</a> to view dependencies with newer versions
<p>You can use <ahref="../cli/npm-outdated.html">npm-outdated(1)</a> to view dependencies with newer versions
available.</p>
available.</p>
<h3id="other-notes">Other Notes</h3>
<h3id="Other-Notes">Other Notes</h3>
<p>A shrinkwrap file must be consistent with the package's package.json
<p>A shrinkwrap file must be consistent with the package's package.json
file. "npm shrinkwrap" will fail if required dependencies are not
file. "npm shrinkwrap" will fail if required dependencies are not
already installed, since that would result in a shrinkwrap that
already installed, since that would result in a shrinkwrap that
wouldn't actually work. Similarly, the command will fail if there are
wouldn't actually work. Similarly, the command will fail if there are
extraneous packages (not referenced by package.json), since that would
extraneous packages (not referenced by package.json), since that would
indicate that package.json is not correct.</p>
indicate that package.json is not correct.</p>
<p>Since "npm shrinkwrap" is intended to lock down your dependencies for
<p>Since "npm shrinkwrap" is intended to lock down your dependencies for
production use, <code>devDependencies</code> will not be included unless you
production use, <code>devDependencies</code> will not be included unless you
explicitly set the <code>--dev</code> flag when you run <code>npm shrinkwrap</code>. If
explicitly set the <code>--dev</code> flag when you run <code>npm shrinkwrap</code>. If
installed <code>devDependencies</code> are excluded, then npm will print a
installed <code>devDependencies</code> are excluded, then npm will print a
warning. If you want them to be installed with your module by
warning. If you want them to be installed with your module by
default, please consider adding them to <code>dependencies</code> instead.</p>
default, please consider adding them to <code>dependencies</code> instead.</p>
<p>If shrinkwrapped package A depends on shrinkwrapped package B, B'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,
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
because A's shrinkwrap is constructed from a valid installation of B
and recursively specifies all dependencies, the contents of B's
and recursively specifies all dependencies, the contents of B's
shrinkwrap will implicitly be included in A's shrinkwrap.</p>
shrinkwrap will implicitly be included in A's shrinkwrap.</p>
<h3id="caveats">Caveats</h3>
<h3id="Caveats">Caveats</h3>
<p>Shrinkwrap files only lock down package versions, not actual package
<p>Shrinkwrap files only lock down package versions, not actual package
contents. While discouraged, a package author can republish an
contents. While discouraged, a package author can republish an
existing version of a package, causing shrinkwrapped packages using
existing version of a package, causing shrinkwrapped packages using
@ -175,16 +149,18 @@ want to avoid any risk that a byzantine author replaces a package
you're using with code that breaks your application, you could modify
you're using with code that breaks your application, you could modify
the shrinkwrap file to use git URL references rather than version
the shrinkwrap file to use git URL references rather than version
numbers so that npm always fetches all packages from git.</p>
numbers so that npm always fetches all packages from git.</p>
<p>If you wish to lock down the specific bytes included in a package, for
<p>If you wish to lock down the specific bytes included in a package, for
example to have 100% confidence in being able to reproduce a
example to have 100% confidence in being able to reproduce a
deployment or build, then you ought to check your dependencies into
deployment or build, then you ought to check your dependencies into
source control, or pursue some other mechanism that can verify
source control, or pursue some other mechanism that can verify
npm rm (with any of the previous argument usage)</code></pre>
npm rm (with any of the previous argument usage)
</code></pre><h2id="description">DESCRIPTION</h2>
<h2id="DESCRIPTION">DESCRIPTION</h2>
<p>This uninstalls a package, completely removing everything npm installed
<p>This uninstalls a package, completely removing everything npm installed
on its behalf.</p>
on its behalf.</p>
<p>Example:</p>
<p>Example:</p>
<pre><code>npm uninstall sax
<pre><code>npm uninstall sax</code></pre>
</code></pre><p>In global mode (ie, with <code>-g</code> or <code>--global</code> appended to the command),
<p>In global mode (ie, with <code>-g</code> or <code>--global</code> appended to the command),
it uninstalls the current package context as a global package.</p>
it uninstalls the current package context as a global package.</p>
<p><code>npm uninstall</code> takes 3 exclusive, optional flags which save or update
<p><code>npm uninstall</code> takes 3 exclusive, optional flags which save or update
the package version in your main package.json:</p>
the package version in your main package.json:</p>
<ul>
<ul><li><p><code>--save</code>: Package will be removed from your <code>dependencies</code>.</p></li><li><p><code>--save-dev</code>: Package will be removed from your <code>devDependencies</code>.</p></li><li><p><code>--save-optional</code>: Package will be removed from your <code>optionalDependencies</code>.</p></li></ul>
<li><p><code>--save</code>: Package will be removed from your <code>dependencies</code>.</p>
</li>
<li><p><code>--save-dev</code>: Package will be removed from your <code>devDependencies</code>.</p>
</li>
<li><p><code>--save-optional</code>: Package will be removed from your <code>optionalDependencies</code>.</p>
<p>npm is the package manager for the Node JavaScript platform. It puts
<p>npm is the package manager for the Node JavaScript platform. It puts
modules in place so that node can find them, and manages dependency
modules in place so that node can find them, and manages dependency
conflicts intelligently.</p>
conflicts intelligently.</p>
<p>It is extremely configurable to support a wide variety of use cases.
<p>It is extremely configurable to support a wide variety of use cases.
Most commonly, it is used to publish, discover, install, and develop node
Most commonly, it is used to publish, discover, install, and develop node
programs.</p>
programs.</p>
<p>Run <code>npm help</code> to get a list of available commands.</p>
<p>Run <code>npm help</code> to get a list of available commands.</p>
<h2id="introduction">INTRODUCTION</h2>
<h2id="INTRODUCTION">INTRODUCTION</h2>
<p>You probably got npm because you want to install stuff.</p>
<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="../cli/npm-install.html">npm-install(1)</a></code> for more info. It can do a lot of stuff.</p>
<code><ahref="../cli/npm-install.html">npm-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.
<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>
Use <code>npm ls</code> to show everything you've installed.</p>
<h2id="directories">DIRECTORIES</h2>
<h2id="DIRECTORIES">DIRECTORIES</h2>
<p>See <code><ahref="../files/npm-folders.html">npm-folders(5)</a></code> to learn about where npm puts stuff.</p>
<p>See <code><ahref="../files/npm-folders.html">npm-folders(5)</a></code> to learn about where npm puts stuff.</p>
<p>In particular, npm has two modes of operation:</p>
<p>In particular, npm has two modes of operation:</p>
<ul>
<ul><li>global mode:<br/>npm installs packages into the install prefix at
<li>global mode:<br>npm installs packages into the install prefix at
<code>prefix/lib/node_modules</code> and bins are installed in <code>prefix/bin</code>.</li><li>local mode:<br/>npm installs packages into the current project directory, which
<code>prefix/lib/node_modules</code> and bins are installed in <code>prefix/bin</code>.</li>
<li>local mode:<br>npm installs packages into the current project directory, which
defaults to the current working directory. Packages are installed to
defaults to the current working directory. Packages are installed to
<code>./node_modules</code>, and bins are installed to <code>./node_modules/.bin</code>.</li></ul>
<code>./node_modules</code>, and bins are installed to <code>./node_modules/.bin</code>.</li>
</ul>
<p>Local mode is the default. Use <code>--global</code> or <code>-g</code> on any command to
<p>Local mode is the default. Use <code>--global</code> or <code>-g</code> on any command to
operate in global mode instead.</p>
operate in global mode instead.</p>
<h2id="developer-usage">DEVELOPER USAGE</h2>
<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>
following help topics:</p>
<ul>
<ul><li>json:
<li>json:
Make a package.json file. See <code><ahref="../files/package.json.html">package.json(5)</a></code>.</li><li>link:
Make a package.json file. See <code><ahref="../files/package.json.html">package.json(5)</a></code>.</li>
<li>link:
For linking your current working code into Node's path, so that you
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
don't have to reinstall every time you make a change. Use
<code>npm link</code> to do this.</li><li>install:
<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
Especially, installing other peoples code from the registry is done via
<code>npm install</code></li><li>adduser:
<code>npm install</code></li>
<li>adduser:
Create an account or log in. Credentials are stored in the
Create an account or log in. Credentials are stored in the
user config file.</li><li>publish:
user config file.</li>
Use the <code>npm publish</code> command to upload your code to the registry.</li></ul>
<li>publish:
Use the <code>npm publish</code> command to upload your code to the registry.</li>
<h2id="CONFIGURATION">CONFIGURATION</h2>
</ul>
<h2id="configuration">CONFIGURATION</h2>
<p>npm is extremely configurable. It reads its configuration options from
<p>npm is extremely configurable. It reads its configuration options from
5 places.</p>
5 places.</p>
<ul>
<ul><li>Command line switches:<br/>Set a config with <code>--key val</code>. All keys take a value, even if they
<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
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
to boolean <code>true</code>.</li>
<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
<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
present, it is parsed. If the <code>userconfig</code> option is set in the cli
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
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.
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,
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>
lib/utils/config-defs.js. These must not be changed.</li></ul>
<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="../misc/npm-config.html">npm-config(7)</a></code> for much much more information.</p>
<p>See <code><ahref="../misc/npm-config.html">npm-config(7)</a></code> for much much more information.</p>
<h2id="contributions">CONTRIBUTIONS</h2>
<h2id="CONTRIBUTIONS">CONTRIBUTIONS</h2>
<p>Patches welcome!</p>
<p>Patches welcome!</p>
<ul>
<ul><li>code:
<li>code:
Read through <code><ahref="../misc/npm-coding-style.html">npm-coding-style(7)</a></code> if you plan to submit code.
Read through <code><ahref="../misc/npm-coding-style.html">npm-coding-style(7)</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
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>
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
<h1><ahref="../files/npm-folders.html">npm-folders</a></h1><p>Folder Structures Used by npm</p>
<h1><ahref="../files/npm-folders.html">npm-folders</a></h1><p>Folder Structures Used by npm</p>
<h2id="description">DESCRIPTION</h2>
<h2id="DESCRIPTION">DESCRIPTION</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>
<p>This document will tell you what it puts where.</p>
<h3id="tl-dr">tl;dr</h3>
<h3id="tl-dr">tl;dr</h3>
<ul>
<ul><li>Local install (default): puts stuff in <code>./node_modules</code> of the current
<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
package root.</li>
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>
<li>Global install (with <code>-g</code>): puts stuff in /usr/local or wherever node
<h1><ahref="../files/npm-folders.html">npm-folders</a></h1><p>Folder Structures Used by npm</p>
<h1><ahref="../files/npm-folders.html">npm-folders</a></h1><p>Folder Structures Used by npm</p>
<h2id="description">DESCRIPTION</h2>
<h2id="DESCRIPTION">DESCRIPTION</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>
<p>This document will tell you what it puts where.</p>
<h3id="tl-dr">tl;dr</h3>
<h3id="tl-dr">tl;dr</h3>
<ul>
<ul><li>Local install (default): puts stuff in <code>./node_modules</code> of the current
<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
package root.</li>
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>
<li>Global install (with <code>-g</code>): puts stuff in /usr/local or wherever node
</code></pre><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
<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>
override that by doing <code>npm config set foo:port 8001</code>.</p>
<p>See <code><ahref="../misc/npm-config.html">npm-config(7)</a></code> and <code><ahref="../misc/npm-scripts.html">npm-scripts(7)</a></code> for more on package
<p>See <code><ahref="../misc/npm-config.html">npm-config(7)</a></code> and <code><ahref="../misc/npm-scripts.html">npm-scripts(7)</a></code> for more on package
configs.</p>
configs.</p>
<h2id="dependencies">dependencies</h2>
<h2id="dependencies">dependencies</h2>
<p>Dependencies are specified with a simple hash of package name to
<p>Dependencies are specified with a simple hash of package name to
version range. The version range is a string which has one or more
version range. The version range is a string which has one or more
space-separated descriptors. Dependencies can also be identified with
space-separated descriptors. Dependencies can also be identified with
a tarball or git URL.</p>
a tarball or git URL.</p>
<p><strong>Please do not put test harnesses or transpilers in your
<p><strong>Please do not put test harnesses or transpilers in your
<code>dependencies</code> hash.</strong> See <code>devDependencies</code>, below.</p>
<code>dependencies</code> hash.</strong> See <code>devDependencies</code>, below.</p>
<p>See <ahref="../misc/semver.html">semver(7)</a> for more details about specifying version ranges.</p>
<p>See <ahref="../misc/semver.html">semver(7)</a> for more details about specifying version ranges.</p>
<ul>
<ul><li><code>version</code> Must match <code>version</code> exactly</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>"Approximately equivalent to version" See <ahref="../misc/semver.html">semver(7)</a></li><li><code>^version</code>"Compatible with version" See <ahref="../misc/semver.html">semver(7)</a></li><li><code>1.2.x</code> 1.2.0, 1.2.1, etc., but not 1.3.0</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><li><code>user/repo</code> See 'GitHub URLs' below</li></ul>
<li><code>version</code> Must match <code>version</code> exactly</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>"Approximately equivalent to version" See <ahref="../misc/semver.html">semver(7)</a></li>
<li><code>^version</code>"Compatible with version" See <ahref="../misc/semver.html">semver(7)</a></li>
<li><code>1.2.x</code> 1.2.0, 1.2.1, etc., but not 1.3.0</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>
<li><code>user/repo</code> See 'GitHub URLs' below</li>
<p>The host architecture is determined by <code>process.arch</code></p>
<h2id="preferGlobal">preferGlobal</h2>
<p>If your package is primarily a command-line application that should be
<p>If your package is primarily a command-line application that should be
installed globally, then set this value to <code>true</code> to provide a warning
installed globally, then set this value to <code>true</code> to provide a warning
if it is installed locally.</p>
if it is installed locally.</p>
<p>It doesn't actually prevent users from installing it locally, but it
<p>It doesn't actually prevent users from installing it locally, but it
does help prevent some confusion if it doesn't work as expected.</p>
does help prevent some confusion if it doesn't work as expected.</p>
<h2id="private">private</h2>
<h2id="private">private</h2>
<p>If you set <code>"private": true</code> in your package.json, then npm will refuse
<p>If you set <code>"private": true</code> in your package.json, then npm will refuse
to publish it.</p>
to publish it.</p>
<p>This is a way to prevent accidental publication of private repositories.
<p>This is a way to prevent accidental publication of private repositories.
If you would like to ensure that a given package is only ever published
If you would like to ensure that a given package is only ever published
to a specific registry (for example, an internal registry),
to a specific registry (for example, an internal registry),
then use the <code>publishConfig</code> hash described below
then use the <code>publishConfig</code> hash described below
to override the <code>registry</code> config param at publish-time.</p>
to override the <code>registry</code> config param at publish-time.</p>
<h2id="publishconfig">publishConfig</h2>
<h2id="publishConfig">publishConfig</h2>
<p>This is a set of config values that will be used at publish-time. It's
<p>This is a set of config values that will be used at publish-time. It's
especially handy if you want to set the tag or registry, so that you can
especially handy if you want to set the tag or registry, so that you can
ensure that a given package is not tagged with "latest" or published to
ensure that a given package is not tagged with "latest" or published to
the global public registry by default.</p>
the global public registry by default.</p>
<p>Any config values can be overridden, but of course only "tag" and
<p>Any config values can be overridden, but of course only "tag" and
"registry" probably matter for the purposes of publishing.</p>
"registry" probably matter for the purposes of publishing.</p>
<p>See <code><ahref="../misc/npm-config.html">npm-config(7)</a></code> to see the list of config options that can be
<p>See <code><ahref="../misc/npm-config.html">npm-config(7)</a></code> to see the list of config options that can be
overridden.</p>
overridden.</p>
<h2id="default-values">DEFAULT VALUES</h2>
<h2id="DEFAULT-VALUES">DEFAULT VALUES</h2>
<p>npm will default some values based on package contents.</p>
<p>npm will default some values based on package contents.</p>
<ul>
<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-gyp rebuild"}</code></p><p>If there is a <code>binding.gyp</code> file in the root of your package, npm will
<p>If there is a <code>server.js</code> file in the root of your package, then npm
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
will default the <code>start</code> command to <code>node server.js</code>.</p>
</code></pre><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
<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>
override that by doing <code>npm config set foo:port 8001</code>.</p>
<p>See <code><ahref="../misc/npm-config.html">npm-config(7)</a></code> and <code><ahref="../misc/npm-scripts.html">npm-scripts(7)</a></code> for more on package
<p>See <code><ahref="../misc/npm-config.html">npm-config(7)</a></code> and <code><ahref="../misc/npm-scripts.html">npm-scripts(7)</a></code> for more on package
configs.</p>
configs.</p>
<h2id="dependencies">dependencies</h2>
<h2id="dependencies">dependencies</h2>
<p>Dependencies are specified with a simple hash of package name to
<p>Dependencies are specified with a simple hash of package name to
version range. The version range is a string which has one or more
version range. The version range is a string which has one or more
space-separated descriptors. Dependencies can also be identified with
space-separated descriptors. Dependencies can also be identified with
a tarball or git URL.</p>
a tarball or git URL.</p>
<p><strong>Please do not put test harnesses or transpilers in your
<p><strong>Please do not put test harnesses or transpilers in your
<code>dependencies</code> hash.</strong> See <code>devDependencies</code>, below.</p>
<code>dependencies</code> hash.</strong> See <code>devDependencies</code>, below.</p>
<p>See <ahref="../misc/semver.html">semver(7)</a> for more details about specifying version ranges.</p>
<p>See <ahref="../misc/semver.html">semver(7)</a> for more details about specifying version ranges.</p>
<ul>
<ul><li><code>version</code> Must match <code>version</code> exactly</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>"Approximately equivalent to version" See <ahref="../misc/semver.html">semver(7)</a></li><li><code>^version</code>"Compatible with version" See <ahref="../misc/semver.html">semver(7)</a></li><li><code>1.2.x</code> 1.2.0, 1.2.1, etc., but not 1.3.0</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><li><code>user/repo</code> See 'GitHub URLs' below</li></ul>
<li><code>version</code> Must match <code>version</code> exactly</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>"Approximately equivalent to version" See <ahref="../misc/semver.html">semver(7)</a></li>
<li><code>^version</code>"Compatible with version" See <ahref="../misc/semver.html">semver(7)</a></li>
<li><code>1.2.x</code> 1.2.0, 1.2.1, etc., but not 1.3.0</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>
<li><code>user/repo</code> See 'GitHub URLs' below</li>
<p>The host architecture is determined by <code>process.arch</code></p>
<h2id="preferGlobal">preferGlobal</h2>
<p>If your package is primarily a command-line application that should be
<p>If your package is primarily a command-line application that should be
installed globally, then set this value to <code>true</code> to provide a warning
installed globally, then set this value to <code>true</code> to provide a warning
if it is installed locally.</p>
if it is installed locally.</p>
<p>It doesn't actually prevent users from installing it locally, but it
<p>It doesn't actually prevent users from installing it locally, but it
does help prevent some confusion if it doesn't work as expected.</p>
does help prevent some confusion if it doesn't work as expected.</p>
<h2id="private">private</h2>
<h2id="private">private</h2>
<p>If you set <code>"private": true</code> in your package.json, then npm will refuse
<p>If you set <code>"private": true</code> in your package.json, then npm will refuse
to publish it.</p>
to publish it.</p>
<p>This is a way to prevent accidental publication of private repositories.
<p>This is a way to prevent accidental publication of private repositories.
If you would like to ensure that a given package is only ever published
If you would like to ensure that a given package is only ever published
to a specific registry (for example, an internal registry),
to a specific registry (for example, an internal registry),
then use the <code>publishConfig</code> hash described below
then use the <code>publishConfig</code> hash described below
to override the <code>registry</code> config param at publish-time.</p>
to override the <code>registry</code> config param at publish-time.</p>
<h2id="publishconfig">publishConfig</h2>
<h2id="publishConfig">publishConfig</h2>
<p>This is a set of config values that will be used at publish-time. It's
<p>This is a set of config values that will be used at publish-time. It's
especially handy if you want to set the tag or registry, so that you can
especially handy if you want to set the tag or registry, so that you can
ensure that a given package is not tagged with "latest" or published to
ensure that a given package is not tagged with "latest" or published to
the global public registry by default.</p>
the global public registry by default.</p>
<p>Any config values can be overridden, but of course only "tag" and
<p>Any config values can be overridden, but of course only "tag" and
"registry" probably matter for the purposes of publishing.</p>
"registry" probably matter for the purposes of publishing.</p>
<p>See <code><ahref="../misc/npm-config.html">npm-config(7)</a></code> to see the list of config options that can be
<p>See <code><ahref="../misc/npm-config.html">npm-config(7)</a></code> to see the list of config options that can be
overridden.</p>
overridden.</p>
<h2id="default-values">DEFAULT VALUES</h2>
<h2id="DEFAULT-VALUES">DEFAULT VALUES</h2>
<p>npm will default some values based on package contents.</p>
<p>npm will default some values based on package contents.</p>
<ul>
<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-gyp rebuild"}</code></p><p>If there is a <code>binding.gyp</code> file in the root of your package, npm will
<p>If there is a <code>server.js</code> file in the root of your package, then npm
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
will default the <code>start</code> command to <code>node server.js</code>.</p>
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.
<li>null loops like: <code>while (something) ;</code> (But you'd better have a good
<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>
your project.</p>
<p>Fantastic!</p>
<p>Fantastic!</p>
<p>There are a few things that you need to do above the simple steps
<p>There are a few things that you need to do above the simple steps
that your users will do to install your program.</p>
that your users will do to install your program.</p>
<h2id="about-these-documents">About These Documents</h2>
<h2id="About-These-Documents">About These Documents</h2>
<p>These are man pages. If you install npm, you should be able to
<p>These are man pages. If you install npm, you should be able to
then do <code>man npm-thing</code> to get the documentation on a particular
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>
topic, or <code>npm help thing</code> to see the same information.</p>
<h2id="what-is-a-package-">What is a <code>package</code></h2>
<h2id="What-is-a-package">What is a <code>package</code></h2>
<p>A package is:</p>
<p>A package is:</p>
<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>
<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
<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
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
perhaps if you also want to be able to easily install it elsewhere
<p>You need to have a <code>package.json</code> file in the root of your project to do
<p>You need to have a <code>package.json</code> file in the root of your project to do
much of anything with npm. That is basically the whole interface.</p>
much of anything with npm. That is basically the whole interface.</p>
<p>See <code><ahref="../files/package.json.html">package.json(5)</a></code> for details about what goes in that file. At the very
<p>See <code><ahref="../files/package.json.html">package.json(5)</a></code> for details about what goes in that file. At the very
least, you need:</p>
least, you need:</p>
<ul>
<ul><li><p>name:
<li><p>name:
This should be a string that identifies your project. Please do not
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.
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
You can use the "engines" field to explicitly state the versions of
node (or whatever else) that your program requires, and it's pretty
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:
well assumed that it's javascript.</p>
A semver-compatible version.</p></li><li><p>engines:
<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
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
runs on. The node API changes a lot, and there may be bugs or new
functionality that you depend on. Be explicit.</p></li><li><p>author:
functionality that you depend on. Be explicit.</p>
Take some credit.</p></li><li><p>scripts:
</li>
<li><p>author:
Take some credit.</p>
</li>
<li><p>scripts:
If you have a special compilation or installation script, then you
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
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="../misc/npm-scripts.html">npm-scripts(7)</a>.</p></li><li><p>main:
See <ahref="../misc/npm-scripts.html">npm-scripts(7)</a>.</p>
</li>
<li><p>main:
If you have a single module that serves as the entry point to your
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")),
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:
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
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
"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>
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
<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="../cli/npm-init.html">npm-init(1)</a></code> for
started with a pretty basic package.json file. See <code><ahref="../cli/npm-init.html">npm-init(1)</a></code> for
more info.</p>
more info.</p>
<h2id="keeping-files-out-of-your-package">Keeping files <em>out</em> 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 <code>.npmignore</code> file, but there <em>is</em> a <code>.gitignore</code> file, then npm will
no <code>.npmignore</code> file, but there <em>is</em> a <code>.gitignore</code> file, then npm will
ignore the stuff matched by the <code>.gitignore</code> file. If you <em>want</em> to
ignore the stuff matched by the <code>.gitignore</code> file. If you <em>want</em> to
include something that is excluded by your <code>.gitignore</code> file, you can
include something that is excluded by your <code>.gitignore</code> file, you can
create an empty <code>.npmignore</code> file to override it.</p>
create an empty <code>.npmignore</code> file to override it.</p>
<p>By default, the following paths and files are ignored, so there's no
<p>By default, the following paths and files are ignored, so there's no
need to add them to <code>.npmignore</code> explicitly:</p>
need to add them to <code>.npmignore</code> explicitly:</p>
<h1><ahref="../misc/npm-disputes.html">npm-disputes</a></h1><p>Handling Module Name Disputes</p>
<h1><ahref="../misc/npm-disputes.html">npm-disputes</a></h1><p>Handling Module Name Disputes</p>
<h2id="synopsis">SYNOPSIS</h2>
<h2id="SYNOPSIS">SYNOPSIS</h2>
<ol>
<li>Get the author email with <code>npm owner ls <pkgname></code></li>
<ol><li>Get the author email with <code>npm owner ls <pkgname></code></li><li>Email the author, CC <ahref="mailto:support@npmjs.com">support@npmjs.com</a></li><li>After a few weeks, if there's no resolution, we'll sort it out.</li></ol>
<li>Email the author, CC <ahref="mailto:support@npmjs.com">support@npmjs.com</a></li>
<li>After a few weeks, if there's no resolution, we'll sort it out.</li>
</ol>
<p>Don't squat on package names. Publish code or move out of the way.</p>
<p>Don't squat on package names. Publish code or move out of the way.</p>
<h2id="description">DESCRIPTION</h2>
<h2id="DESCRIPTION">DESCRIPTION</h2>
<p>There sometimes arise cases where a user publishes a module, and then
<p>There sometimes arise cases where a user publishes a module, and then
later, some other user wants to use that name. Here are some common
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>
ways that happens (each of these is based on actual events.)</p>
<ol>
<ol><li>Joe writes a JavaScript module <code>foo</code>, which is not node-specific.
<li>Joe writes a JavaScript module <code>foo</code>, which is not node-specific.
Joe doesn't use node at all. Bob wants to use <code>foo</code> in node, so he
Joe doesn't use node at all. Bob wants to use <code>foo</code> in node, so he
wraps it in an npm module. Some time later, Joe starts using node,
wraps it in an npm module. Some time later, Joe 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
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
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
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
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
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
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
never really has to be updated. Joe works for Foo Inc, the makers
of the critically acclaimed and widely-marketed <code>foo</code> JavaScript
of the critically acclaimed and widely-marketed <code>foo</code> JavaScript
toolkit framework. They publish it to npm as <code>foojs</code>, but people are
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
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
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,
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,
<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>
Joe's appropriate course of action in each case is the same.</p>
<ol>
<ol><li><code>npm owner ls foo</code>. This will tell Joe the email address of the
<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 respectfully as
owner (Bob).</li>
<li>Joe emails Bob, explaining the situation <strong>as respectfully as
possible</strong>, and what he would like to do with the module name. He
possible</strong>, and what he would like to do with the module name. He
adds the npm support staff <ahref="mailto:support@npmjs.com">support@npmjs.com</a> to the CC list of
adds the npm support staff <ahref="mailto:support@npmjs.com">support@npmjs.com</a> to the CC list of
the email. Mention in the email that Bob can run <code>npm owner add
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
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 support
Bob and Joe can't come to any sort of resolution, email support
<ahref="mailto:support@npmjs.com">support@npmjs.com</a> and we'll sort it out. ("Reasonable" is
<ahref="mailto:support@npmjs.com">support@npmjs.com</a> and we'll sort it out. ("Reasonable" is
usually at least 4 weeks, but extra time is allowed around common
usually at least 4 weeks, but extra time is allowed around common
holidays.)</li></ol>
holidays.)</li>
</ol>
<h2id="REASONING">REASONING</h2>
<h2id="reasoning">REASONING</h2>
<p>In almost every case so far, the parties involved have been able to reach
<p>In almost every case so far, the parties involved have been able to reach
an amicable resolution without any major intervention. Most people
an amicable resolution without any major intervention. Most people
really do want to be reasonable, and are probably not even aware that
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
<p>Module ecosystems are most vibrant and powerful when they are as
self-directed as possible. If an admin one day deletes something you
self-directed as possible. If an admin one day deletes something you
had worked on, then that is going to make most people quite upset,
had worked on, then that is going to make most people quite upset,
regardless of the justification. When humans solve their problems by
regardless of the justification. When humans solve their problems by
talking to other humans with respect, everyone has the chance to end up
talking to other humans with respect, everyone has the chance to end up
feeling good about the interaction.</p>
feeling good about the interaction.</p>
<h2id="exceptions">EXCEPTIONS</h2>
<h2id="EXCEPTIONS">EXCEPTIONS</h2>
<p>Some things are not allowed, and will be removed without discussion if
<p>Some things are not allowed, and will be removed without discussion if
they are brought to the attention of the npm registry admins, including
they are brought to the attention of the npm registry admins, including
but not limited to:</p>
but not limited to:</p>
<ol>
<ol><li>Malware (that is, a package designed to exploit or harm the machine on
<li>Malware (that is, a package designed to exploit or harm the machine on
which it is installed).</li><li>Violations of copyright or licenses (for example, cloning an
which it is installed).</li>
<li>Violations of copyright or licenses (for example, cloning an
MIT-licensed program, and then removing or changing the copyright and
MIT-licensed program, and then removing or changing the copyright and
license statement).</li><li>Illegal content.</li><li>"Squatting" on a package name that you <em>plan</em> to use, but aren't
license statement).</li>
<li>Illegal content.</li>
<li>"Squatting" on a package name that you <em>plan</em> to use, but aren't
actually using. Sorry, I don't care how great the name is, or how
actually using. Sorry, I don't care how great the name is, or how
perfect a fit it is for the thing that someday might happen. If
perfect a fit it is for the thing that someday might happen. If
someone wants to use it today, and you're just taking up space with
someone wants to use it today, and you're just taking up space with
an empty tarball, you're going to be evicted.</li><li>Putting empty packages in the registry. Packages must have SOME
an empty tarball, you're going to be evicted.</li>
<li>Putting empty packages in the registry. Packages must have SOME
functionality. It can be silly, but it can't be <em>nothing</em>. (See
functionality. It can be silly, but it can't be <em>nothing</em>. (See
also: squatting.)</li><li>Doing weird things with the registry, like using it as your own
also: squatting.)</li>
<li>Doing weird things with the registry, like using it as your own
personal application database or otherwise putting non-packagey
personal application database or otherwise putting non-packagey
things into it.</li></ol>
things into it.</li>
</ol>
<p>If you see bad behavior like this, please report it right away.</p>
<p>If you see bad behavior like this, please report it right away.</p>
<ul><li>Use the <code>npm root</code> command to see where modules go, and the <code>npm bin</code>
<li>Use the <code>npm root</code> command to see where modules go, and the <code>npm bin</code>
command to see where executables go</li><li>Global installs are different from local installs. If you install
command to see where executables go</li>
<li>Global installs are different from local installs. If you install
something with the <code>-g</code> flag, then its executables go in <code>npm bin -g</code>
something with the <code>-g</code> flag, then its executables go in <code>npm bin -g</code>
and its modules go in <code>npm root -g</code>.</li></ul>
and its modules go in <code>npm root -g</code>.</li>
</ul>
<h2id="How-do-I-install-something-on-my-computer-in-a-central-location">How do I install something on my computer in a central location?</h2>
<h2id="how-do-i-install-something-on-my-computer-in-a-central-location-">How do I install something on my computer in a central location?</h2>
<p>Install it globally by tacking <code>-g</code> or <code>--global</code> to the command. (This
<p>Install it globally by tacking <code>-g</code> or <code>--global</code> to the command. (This
is especially important for command line utilities that need to add
is especially important for command line utilities that need to add
their bins to the global system <code>PATH</code>.)</p>
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 <code>require()</code> 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>Install it locally.</p>
<p>The global install location is a place for command-line utilities
<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
dependency, and a part of your program. You need to install it locally
in your program.</p>
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.
<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
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
not going to happen, because it's a terrible idea that causes more
problems than it solves.</p>
problems than it solves.</p>
<p>It is much harder to avoid dependency conflicts without nesting
<p>It is much harder to avoid dependency conflicts without nesting
dependencies. This is fundamental to the way that npm works, and has
dependencies. This is fundamental to the way that npm works, and has
proven to be an extremely successful approach. See <code><ahref="../files/npm-folders.html">npm-folders(5)</a></code> for
proven to be an extremely successful approach. See <code><ahref="../files/npm-folders.html">npm-folders(5)</a></code> for
more details.</p>
more details.</p>
<p>If you want a package to be installed in one place, and have all your
<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.
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>
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. You could probably even wrap up <code>npm</code>
<p>Write your own package manager. You could probably even wrap up <code>npm</code>
in a shell script if you really wanted to.</p>
in a shell script if you really wanted to.</p>
<p>npm will not help you do something that is known to be a bad idea.</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 <code>node_modules</code> 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>
<p>Mikeal Rogers answered this question very well:</p>
</code></pre><h2id="what-is-a-package-">What is a <code>package</code>?</h2>
<h2id="What-is-a-package">What is a <code>package</code>?</h2>
<p>A package is:</p>
<p>A package is:</p>
<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>
<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
<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
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
perhaps if you also want to be able to easily install it elsewhere
</code></pre><p>The <code>commit-ish</code> can be any tag, sha, or branch which can be supplied as
<p>The <code>commit-ish</code> can be any tag, sha, or branch which can be supplied as
an argument to <code>git checkout</code>. The default is <code>master</code>.</p>
an argument to <code>git checkout</code>. The default is <code>master</code>.</p>
<h2id="what-is-a-module-">What is a <code>module</code>?</h2>
<h2id="What-is-a-module">What is a <code>module</code>?</h2>
<p>A module is anything that can be loaded with <code>require()</code> in a Node.js
<p>A module is anything that can be loaded with <code>require()</code> in a Node.js
program. The following things are all examples of things that can be
program. The following things are all examples of things that can be
loaded as modules:</p>
loaded as modules:</p>
<ul>
<ul><li>A folder with a <code>package.json</code> file containing a <code>main</code> field.</li><li>A folder with an <code>index.js</code> file in it.</li><li>A JavaScript file.</li></ul>
<li>A folder with a <code>package.json</code> file containing a <code>main</code> field.</li>
<li>A folder with an <code>index.js</code> file in it.</li>
<li>A JavaScript file.</li>
</ul>
<p>Most npm packages are modules, because they are libraries that you
<p>Most npm packages are modules, because they are libraries that you
load with <code>require</code>. However, there's no requirement that an npm
load with <code>require</code>. However, there's no requirement that an npm
package be a module! Some only contain an executable command-line
package be a module! Some only contain an executable command-line
interface, and don't provide a <code>main</code> field for use in Node programs.</p>
interface, and don't provide a <code>main</code> field for use in Node programs.</p>
<p>Almost all npm packages (at least, those that are Node programs)
<p>Almost all npm packages (at least, those that are Node programs)
<em>contain</em> many modules within them (because every file they load with
<em>contain</em> many modules within them (because every file they load with
<code>require()</code> is a module).</p>
<code>require()</code> is a module).</p>
<p>In the context of a Node program, the <code>module</code> is also the thing that
<p>In the context of a Node program, the <code>module</code> is also the thing that
was loaded <em>from</em> a file. For example, in the following program:</p>
was loaded <em>from</em> a file. For example, in the following program:</p>
</code></pre><p>we might say that "The variable <code>req</code> refers to the <code>request</code> module".</p>
<h2id="so-why-is-it-the-node_modules-folder-but-package-json-file-why-not-node_packages-or-module-json-">So, why is it the "<code>node_modules</code>" folder, but "<code>package.json</code>" file? Why not <code>node_packages</code> or <code>module.json</code>?</h2>
<p>we might say that "The variable <code>req</code> refers to the <code>request</code> module".</p>
<h2id="So-why-is-it-the-node_modules-folder-but-package-json-file-Why-not-node_packages-or-module-json">So, why is it the "<code>node_modules</code>" folder, but "<code>package.json</code>" file? Why not <code>node_packages</code> or <code>module.json</code>?</h2>
<p>The <code>package.json</code> file defines the package. (See "What is a
<p>The <code>package.json</code> file defines the package. (See "What is a
package?" above.)</p>
package?" above.)</p>
<p>The <code>node_modules</code> folder is the place Node.js looks for modules.
<p>The <code>node_modules</code> folder is the place Node.js looks for modules.
(See "What is a module?" above.)</p>
(See "What is a module?" above.)</p>
<p>For example, if you create a file at <code>node_modules/foo.js</code> and then
<p>For example, if you create a file at <code>node_modules/foo.js</code> and then
had a program that did <code>var f = require('foo.js')</code> then it would load
had a program that did <code>var f = require('foo.js')</code> then it would load
the module. However, <code>foo.js</code> is not a "package" in this case,
the module. However, <code>foo.js</code> is not a "package" in this case,
because it does not have a package.json.</p>
because it does not have a package.json.</p>
<p>Alternatively, if you create a package which does not have an
<p>Alternatively, if you create a package which does not have an
<code>index.js</code> or a <code>"main"</code> field in the <code>package.json</code> file, then it is
<code>index.js</code> or a <code>"main"</code> field in the <code>package.json</code> file, then it is
not a module. Even if it's installed in <code>node_modules</code>, it can't be
not a module. Even if it's installed in <code>node_modules</code>, it can't be
an argument to <code>require()</code>.</p>
an argument to <code>require()</code>.</p>
<h2id="-node_modules-is-the-name-of-my-deity-s-arch-rival-and-a-forbidden-word-in-my-religion-can-i-configure-npm-to-use-a-different-folder-"><code>"node_modules"</code> is the name of my deity's arch-rival, and a Forbidden Word in my religion. Can I configure npm to use a different folder?</h2>
<h2id="node_modules-is-the-name-of-my-deity-s-arch-rival-and-a-Forbidden-Word-in-my-religion-Can-I-configure-npm-to-use-a-different-folder"><code>"node_modules"</code> is the name of my deity's arch-rival, and a Forbidden Word in my religion. Can I configure npm to use a different folder?</h2>
<p>No. This will never happen. This question comes up sometimes,
<p>No. This will never happen. This question comes up sometimes,
because it seems silly from the outside that npm couldn't just be
because it seems silly from the outside that npm couldn't just be
configured to put stuff somewhere else, and then npm could load them
configured to put stuff somewhere else, and then npm could load them
from there. It's an arbitrary spelling choice, right? What's the big
from there. It's an arbitrary spelling choice, right? What's the big
deal?</p>
deal?</p>
<p>At the time of this writing, the string <code>'node_modules'</code> appears 151
<p>At the time of this writing, the string <code>'node_modules'</code> appears 151
times in 53 separate files in npm and node core (excluding tests and
times in 53 separate files in npm and node core (excluding tests and
documentation).</p>
documentation).</p>
<p>Some of these references are in node's built-in module loader. Since
<p>Some of these references are in node's built-in module loader. Since
npm is not involved <strong>at all</strong> at run-time, node itself would have to
npm is not involved <strong>at all</strong> at run-time, node itself would have to
be configured to know where you've decided to stick stuff. Complexity
be configured to know where you've decided to stick stuff. Complexity
hurdle #1. Since the Node module system is locked, this cannot be
hurdle #1. Since the Node module system is locked, this cannot be
changed, and is enough to kill this request. But I'll continue, in
changed, and is enough to kill this request. But I'll continue, in
deference to your deity's delicate feelings regarding spelling.</p>
deference to your deity's delicate feelings regarding spelling.</p>
<p>Many of the others are in dependencies that npm uses, which are not
<p>Many of the others are in dependencies that npm uses, which are not
necessarily tightly coupled to npm (in the sense that they do not read
necessarily tightly coupled to npm (in the sense that they do not read
npm's configuration files, etc.) Each of these would have to be
npm's configuration files, etc.) Each of these would have to be
configured to take the name of the <code>node_modules</code> folder as a
configured to take the name of the <code>node_modules</code> folder as a
parameter. Complexity hurdle #2.</p>
parameter. Complexity hurdle #2.</p>
<p>Furthermore, npm has the ability to "bundle" dependencies by adding
<p>Furthermore, npm has the ability to "bundle" dependencies by adding
the dep names to the <code>"bundledDependencies"</code> list in package.json,
the dep names to the <code>"bundledDependencies"</code> list in package.json,
which causes the folder to be included in the package tarball. What
which causes the folder to be included in the package tarball. What
@ -249,7 +192,6 @@ if the author of a module bundles its dependencies, and they use a
different spelling for <code>node_modules</code>? npm would have to rename the
different spelling for <code>node_modules</code>? npm would have to rename the
folder at publish time, and then be smart enough to unpack it using
folder at publish time, and then be smart enough to unpack it using
your locally configured name. Complexity hurdle #3.</p>
your locally configured name. Complexity hurdle #3.</p>
<p>Furthermore, what happens when you <em>change</em> this name? Fine, it's
<p>Furthermore, what happens when you <em>change</em> this name? Fine, it's
easy enough the first time, just rename the <code>node_modules</code> folders to
easy enough the first time, just rename the <code>node_modules</code> folders to
<code>./blergyblerp/</code> or whatever name you choose. But what about when you
<code>./blergyblerp/</code> or whatever name you choose. But what about when you
@ -258,98 +200,80 @@ configuration settings, so this would be rather difficult to do
properly. It would have to track every previous value for this
properly. It would have to track every previous value for this
config, and always accept any of them, or else yesterday's install may
config, and always accept any of them, or else yesterday's install may
be broken tomorrow. Complexity hurdle #5.</p>
be broken tomorrow. Complexity hurdle #5.</p>
<p>Never going to happen. The folder is named <code>node_modules</code>. It is
<p>Never going to happen. The folder is named <code>node_modules</code>. It is
written indelibly in the Node Way, handed down from the ancient times
written indelibly in the Node Way, handed down from the ancient times
of Node 0.3.</p>
of Node 0.3.</p>
<h2id="how-do-i-install-node-with-npm-">How do I install node with npm?</h2>
<h2id="How-do-I-install-node-with-npm">How do I install node with npm?</h2>
<p>You don't. Try one of these node version managers:</p>
<p>You don't. Try one of these node version managers:</p>
<h2id="how-can-i-use-npm-for-development-">How can I use npm for development?</h2>
<p>See <code><ahref="../misc/npm-developers.html">npm-developers(7)</a></code> and <code><ahref="../files/package.json.html">package.json(5)</a></code>.</p>
<p>See <code><ahref="../misc/npm-developers.html">npm-developers(7)</a></code> and <code><ahref="../files/package.json.html">package.json(5)</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>
awesomely handy.</p>
<p>To set up your own private registry, check out <code><ahref="../misc/npm-registry.html">npm-registry(7)</a></code>.</p>
<p>To set up your own private registry, check out <code><ahref="../misc/npm-registry.html">npm-registry(7)</a></code>.</p>
<h2id="can-i-list-a-url-as-a-dependency-">Can I list a url as a dependency?</h2>
<h2id="Can-I-list-a-url-as-a-dependency">Can I list a url as a dependency?</h2>
<p>Yes. It should be a url to a gzipped tarball containing a single folder
<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.
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>
<h2id="i-forgot-my-password-and-can-t-publish-how-do-i-reset-it-">I forgot my password, and can't publish. How do I reset it?</h2>
<h2id="I-forgot-my-password-and-can-t-publish-How-do-I-reset-it">I forgot my password, and can't publish. How do I reset it?</h2>
<p>Go to <ahref="https://npmjs.org/forgot">https://npmjs.org/forgot</a>.</p>
<p>Go to <ahref="https://npmjs.org/forgot">https://npmjs.org/forgot</a>.</p>
<h2id="i-get-econnrefused-a-lot-what-s-up-">I get ECONNREFUSED a lot. What's up?</h2>
<h2id="I-get-ECONNREFUSED-a-lot-What-s-up">I get ECONNREFUSED a lot. What's up?</h2>
<p>Either the registry is down, or node's DNS isn't able to reach out.</p>
<p>Either the registry is down, or node's DNS isn't able to reach out.</p>
<p>To check if the registry is down, open up
<p>To check if the registry is down, open up
<ahref="https://registry.npmjs.org/">https://registry.npmjs.org/</a> in a web browser. This will also tell
<ahref="https://registry.npmjs.org/">https://registry.npmjs.org/</a> in a web browser. This will also tell
you if you are just unable to access the internet for some reason.</p>
you if you are just unable to access the internet for some reason.</p>
<p>If the registry IS down, let us know by emailing <ahref="mailto:support@npmjs.com">support@npmjs.com</a>
<p>If the registry IS down, let us know by emailing <ahref="mailto:support@npmjs.com">support@npmjs.com</a>
or posting an issue at <ahref="https://github.com/npm/npm/issues">https://github.com/npm/npm/issues</a>. If it's
or posting an issue at <ahref="https://github.com/npm/npm/issues">https://github.com/npm/npm/issues</a>. If it's
down for the world (and not just on your local network) then we're
down for the world (and not just on your local network) then we're
probably already being pinged about it.</p>
probably already being pinged about it.</p>
<p>You can also often get a faster response by visiting the #npm channel
<p>You can also often get a faster response by visiting the #npm channel
on Freenode IRC.</p>
on Freenode IRC.</p>
<h2id="why-no-namespaces-">Why no namespaces?</h2>
<h2id="Why-no-namespaces">Why no namespaces?</h2>
<p>Please see this discussion: <ahref="https://github.com/npm/npm/issues/798">https://github.com/npm/npm/issues/798</a></p>
<p>Please see this discussion: <ahref="https://github.com/npm/npm/issues/798">https://github.com/npm/npm/issues/798</a></p>
<p>tl;dr - It doesn't actually make things better, and can make them worse.</p>
<p>tl;dr - It doesn't actually make things better, and can make them worse.</p>
<p>If you want to namespace your own packages, you may: simply use the
<p>If you want to namespace your own packages, you may: simply use the
<code>-</code> character to separate the names. npm is a mostly anarchic system.
<code>-</code> character to separate the names. npm is a mostly anarchic system.
There is not sufficient need to impose namespace rules on everyone.</p>
There is not sufficient need to impose namespace rules on everyone.</p>
<h2id="who-does-npm-">Who does npm?</h2>
<h2id="Who-does-npm">Who does npm?</h2>
<p>npm was originally written by Isaac Z. Schlueter, and many others have
<p>npm was originally written by Isaac Z. Schlueter, and many others have
contributed to it, some of them quite substantially.</p>
contributed to it, some of them quite substantially.</p>
<p>The npm open source project, The npm Registry, and <ahref="https://www.npmjs.org">the community
<p>The npm open source project, The npm Registry, and <ahref="https://www.npmjs.org">the community
website</a> are maintained and operated by the
website</a> are maintained and operated by the
good folks at <ahref="https://www.npmjs.com">npm, Inc.</a></p>
good folks at <ahref="https://www.npmjs.com">npm, Inc.</a></p>
<h2id="i-have-a-question-or-request-not-addressed-here-where-should-i-put-it-">I have a question or request not addressed here. Where should I put it?</h2>
<h2id="I-have-a-question-or-request-not-addressed-here-Where-should-I-put-it">I have a question or request not addressed here. Where should I put it?</h2>
isaacs
11 years ago