* 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.
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
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
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
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
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>
<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>
<ul><li>Use <code>sudo</code> for greater safety. Or don't, if you prefer not to.</li><li>npm will downgrade permissions if it's root before running any build
scripts that package authors specified.</li></ul>
<h3id="More-details">More details...</h3>
<ul>
<li>Use <code>sudo</code> for greater safety. Or don't, if you prefer not to.</li>
<li>npm will downgrade permissions if it's root before running any build
scripts that package authors specified.</li>
</ul>
<h3id="more-details-">More details...</h3>
<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
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
support uid switching, then npm will not attempt to change the userid.</p>
<p>If you would like to ensure that npm <strong>always</strong> runs scripts as the
"nobody" user, and have it fail if it cannot downgrade permissions, then
set the following configuration param:</p>
<pre><code>npm config set unsafe-perm false</code></pre>
<p>This will prevent running in unsafe mode, even as non-root users.</p>
<h2id="Uninstalling">Uninstalling</h2>
<pre><code>npm config set unsafe-perm false
</code></pre><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>
<pre><code>sudo npm uninstall npm -g</code></pre>
<p>Or, if that fails,</p>
<pre><code>sudo make uninstall</code></pre>
<h2id="More-Severe-Uninstalling">More Severe Uninstalling</h2>
<pre><code>sudo npm uninstall npm -g
</code></pre><p>Or, if that fails,</p>
<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
npm, but leave behind anything you've installed.</p>
<p>If you would like to remove all the packages that you have installed,
then you can use the <code>npm ls</code> command to find them, and then <code>npm rm</code> to
remove them.</p>
<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>
<pre><code>npm explore npm -g -- sh scripts/clean-old.sh</code></pre>
<p>npm uses two configuration files, one for per-user configs, and another
<pre><code>npm explore npm -g -- sh scripts/clean-old.sh
</code></pre><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>
<pre><code>npm config get userconfig # defaults to ~/.npmrc
npm config get globalconfig # defaults to /usr/local/etc/npmrc</code></pre>
<p>Uninstalling npm does not remove configuration files by default. You
npm config get globalconfig # defaults to /usr/local/etc/npmrc
</code></pre><p>Uninstalling npm does not remove configuration files by default. You
must remove them yourself manually if you want them gone. Note 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.
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
npm does, you should try using one of npm's dependencies rather than
using npm itself, if possible.</p>
<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
use npm itself to do.</p>
<pre><code>var npm = require("npm")
npm.load(myConfigObject, function (er) {
if (er) return handlError(er)
@ -165,90 +109,72 @@ npm.load(myConfigObject, function (er) {
// command succeeded, and data might have some info
})
npm.on("log", function (message) { .... })
})</code></pre>
<p>The <code>load</code> function takes an object hash of the command-line configs.
})
</code></pre><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
positional argument <strong>strings</strong>. The last argument to any
<code>npm.commands.<cmd></code> function is a callback. Some commands take other
optional arguments. Read the source.</p>
<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
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
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>
<h2id="More-Docs">More Docs</h2>
<h2id="more-docs">More Docs</h2>
<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>
<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,
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.
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>Modules published on the npm registry are not officially endorsed by
npm, Inc. or the Node.js project.</p>
<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
ensure accountability, there is absolutely no guarantee, warrantee, or
assertion expressed or implied as to the quality, fitness for a
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,
and cannot <ahref="https://www.npmjs.org/doc/misc/npm-disputes.html">resolve it with the package
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
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>
<h2id="SYNOPSIS">SYNOPSIS</h2>
<h2id="synopsis">SYNOPSIS</h2>
<pre><code>npm.commands.config(args, callback)
var val = npm.config.get(key)
npm.config.set(key, val)</code></pre>
<h2id="DESCRIPTION">DESCRIPTION</h2>
npm.config.set(key, val)
</code></pre><h2id="description">DESCRIPTION</h2>
<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>
<ul><li><p><code>set</code></p><p>Sets a config parameter. The second element in <code>args</code> is interpreted as the
key, and the third element is interpreted as the value.</p></li><li><p><code>get</code></p><p>Gets the value of a config parameter. The second element in <code>args</code> is the
key to get the value of.</p></li><li><p><code>delete</code> (<code>rm</code> or <code>del</code>)</p><p>Deletes a parameter from the config. The second element in <code>args</code> is the
key to delete.</p></li><li><p><code>list</code> (<code>ls</code>)</p><p>Show all configs that aren't secret. No parameters necessary.</p></li><li><p><code>edit</code>:</p><p>Opens the config file in the default editor. This command isn't very useful
programmatically, but it is made available.</p></li></ul>
<ul>
<li><p><code>set</code></p>
<p> Sets a config parameter. The second element in <code>args</code> is interpreted as the
key, and the third element is interpreted as the value.</p>
</li>
<li><p><code>get</code></p>
<p> Gets the value of a config parameter. The second element in <code>args</code> is the
key to get the value of.</p>
</li>
<li><p><code>delete</code> (<code>rm</code> or <code>del</code>)</p>
<p> Deletes a parameter from the config. The second element in <code>args</code> is the
key to delete.</p>
</li>
<li><p><code>list</code> (<code>ls</code>)</p>
<p> Show all configs that aren't secret. No parameters necessary.</p>
</li>
<li><p><code>edit</code>:</p>
<p> Opens the config file in the default editor. This command isn't very useful
programmatically, but it is made available.</p>
</li>
</ul>
<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>
<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
immediately terminates.</p>
<p>Note that the package is <em>not</em> automatically rebuilt afterwards, so be
sure to use <code>npm rebuild <pkg></code> if you make any changes.</p>
<p>The first element in the 'args' parameter must be a package name. After that is the optional command, which can be any number of strings. All of the strings will be combined into one, space-delimited command.</p>
<p>Search the registry for packages matching the search terms. The available parameters are:</p>
<ul><li>searchTerms:
Array of search terms. These terms are case-insensitive.</li><li>silent:
If true, npm will not log anything to the console.</li><li>staleness:
<ul>
<li>searchTerms:
Array of search terms. These terms are case-insensitive.</li>
<li>silent:
If true, npm will not log anything to the console.</li>
<li>staleness:
This is the threshold for stale packages. "Fresh" packages are not refreshed
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
is information about that package along with a 'words' property, which is
a space-delimited string of all of the interesting words in that package.
The only properties included are those that are searched, which generally include:</p><ul><li>name</li><li>description</li><li>maintainers</li><li>url</li><li>keywords</li></ul></li></ul>
The only properties included are those that are searched, which generally include:</p>
<ul>
<li>name</li>
<li>description</li>
<li>maintainers</li>
<li>url</li>
<li>keywords</li>
</ul>
</li>
</ul>
<p>A search on the registry excludes any result that does not match all of the
search terms. It also removes any items from the results that contain an
excluded term (the "searchexclude" config). The search is case insensitive
and doesn't try to read your mind (it doesn't do any verb tense matching or the
<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>
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.
If you provide <code>configObject</code> as an object hash of top-level
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
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>
<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
all possible commands.</p>
<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
commands take other optional arguments.</p>
<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>
<p>To find API documentation for a specific command, run the <code>npm apihelp</code>
command.</p>
<h2id="METHODS-AND-PROPERTIES">METHODS AND PROPERTIES</h2>
<ul><li><p><code>npm.load(configs, cb)</code></p><p>Load the configuration params, and call the <code>cb</code> function once the
<h2id="methods-and-properties">METHODS AND PROPERTIES</h2>
<ul>
<li><p><code>npm.load(configs, cb)</code></p>
<p>Load the configuration params, and call the <code>cb</code> function once the
globalconfig and userconfig files have been loaded as well, or on
nextTick if they've already been loaded.</p></li><li><p><code>npm.config</code></p><p>An object for accessing npm configuration parameters.</p><ul><li><p><code>npm.config.get(key)</code></p></li><li><code>npm.config.set(key, val)</code></li><li><p><code>npm.config.del(key)</code></p></li></ul></li><li><p><code>npm.dir</code> or <code>npm.root</code></p><p>The <code>node_modules</code> directory where npm will operate.</p></li><li><p><code>npm.prefix</code></p><p>The prefix where npm is operating. (Most often the current working
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>
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><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
the npm object, which takes a set of positional string arguments rather
than an array and a callback.</p>
<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
the error or results.</p>
<p>For example, this would work in a node repl:</p>
npm i (with any of the previous argument usage)</code></pre>
<h2id="DESCRIPTION">DESCRIPTION</h2>
npm i (with any of the previous argument usage)
</code></pre><h2id="description">DESCRIPTION</h2>
<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
by that. See <ahref="../cli/npm-shrinkwrap.html">npm-shrinkwrap(1)</a>.</p>
<p>A <code>package</code> is:</p>
<ul><li>a) a folder containing a program described by a package.json file</li><li>b) a gzipped tarball containing (a)</li><li>c) a url that resolves to (b)</li><li>d) a <code><name>@<version></code> that is published on the registry (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>
<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
benefits of using npm if you just want to write a node program (a), and
perhaps if you also want to be able to easily install it elsewhere
after packing it up into a tarball (b).</p>
<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),
<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),
it installs the current package context (ie, the current working
directory) as a global package.</p><p>By default, <code>npm install</code> will install all modules listed as
directory) as a global package.</p>
<p> By default, <code>npm install</code> will install all modules listed as
dependencies. With the <code>--production</code> flag,
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
npm will not install modules listed in <code>devDependencies</code>.</p>
<p> Install a package that is sitting on the filesystem. Note: if you just want
to link a dev directory into your npm root, you can do this more easily by
using <code>npm link</code>.</p><p>Example:</p><pre><code> npm install ./package.tgz</code></pre></li><li><p><code>npm install <tarball url></code>:</p><p>Fetch the tarball url, and then install it. In order to distinguish between
this and other options, the argument must start with "http://" or "https://"</p><p>Example:</p><pre><code> npm install https://github.com/indexzero/forever/tarball/v0.5.6</code></pre></li><li><p><code>npm install <name> [--save|--save-dev|--save-optional]</code>:</p><p>Do a <code><name>@<tag></code> install, where <code><tag></code> is the "tag" config. (See
<code><ahref="../misc/npm-config.html">npm-config(7)</a></code>.)</p><p>In most cases, this will install the latest version
of the module published on npm.</p><p>Example:</p><p> npm install sax</p><p><code>npm install</code> takes 3 exclusive, optional flags which save or update
the package version in your main package.json:</p><ul><li><p><code>--save</code>: Package will appear in your <code>dependencies</code>.</p></li><li><p><code>--save-dev</code>: Package will appear in your <code>devDependencies</code>.</p></li><li><p><code>--save-optional</code>: Package will appear in your <code>optionalDependencies</code>.</p><p>When using any of the above options to save dependencies to your
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 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
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.
<p> Install the version of the package that is referenced by the specified tag.
If the tag does not exist in the registry data for that package, then this
will fail.</p><p>Example:</p><pre><code> npm install sax@latest</code></pre></li><li><p><code>npm install <name>@<version></code>:</p><p>Install the specified version of the package. This will fail if the version
has not been published to the registry.</p><p>Example:</p><pre><code> npm install sax@0.1.1</code></pre></li><li><p><code>npm install <name>@<version range></code>:</p><p>Install a version of the package matching the specified version range. This
will follow the same rules for resolving dependencies described in <code><ahref="../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
treat it as a single argument.</p><p>Example:</p><p> npm install sax@">=0.1.0 <0.2.0"</p></li><li><p><code>npm install <git remote url></code>:</p><p>Install a package by cloning a git remote url. The format of the git
url is:</p><p><protocol>://[<user>@]<hostname><separator><path>[#<commit-ish>]</p><p><code><protocol></code> is one of <code>git</code>, <code>git+ssh</code>, <code>git+http</code>, or
<ol><li>Run "npm install" in the package root to install the current
versions of all dependencies.</li><li>Validate that the package works as expected with these versions.</li><li>Run "npm shrinkwrap", add npm-shrinkwrap.json to git, and publish
your package.</li></ol>
<ol>
<li>Run "npm install" in the package root to install the current
versions of all dependencies.</li>
<li>Validate that the package works as expected with these versions.</li>
<li>Run "npm shrinkwrap", add npm-shrinkwrap.json to git, and publish
your package.</li>
</ol>
<p>To add or update a dependency in a shrinkwrapped package:</p>
<ol><li>Run "npm install" in the package root to install the current
versions of all dependencies.</li><li>Add or update dependencies. "npm install" each new or updated
<ol>
<li>Run "npm install" in the package root to install the current
versions of all dependencies.</li>
<li>Add or update dependencies. "npm install" each new or updated
package individually and then update package.json. Note that they
must be explicitly named in order to be installed: running <code>npm
install</code> with no arguments will merely reproduce the existing
shrinkwrap.</li><li>Validate that the package works as expected with the new
dependencies.</li><li>Run "npm shrinkwrap", commit the new npm-shrinkwrap.json, and
publish your package.</li></ol>
shrinkwrap.</li>
<li>Validate that the package works as expected with the new
dependencies.</li>
<li>Run "npm shrinkwrap", commit the new npm-shrinkwrap.json, and
publish your package.</li>
</ol>
<p>You can use <ahref="../cli/npm-outdated.html">npm-outdated(1)</a> to view dependencies with newer versions
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
file. "npm shrinkwrap" will fail if required dependencies are not
already installed, since that would result in a shrinkwrap that
wouldn't actually work. Similarly, the command will fail if there are
extraneous packages (not referenced by package.json), since that would
indicate that package.json is not correct.</p>
<p>Since "npm shrinkwrap" is intended to lock down your dependencies for
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
installed <code>devDependencies</code> are excluded, then npm will print a
warning. If you want them to be installed with your module by
default, please consider adding them to <code>dependencies</code> instead.</p>
<p>If shrinkwrapped package A depends on shrinkwrapped package B, B's
shrinkwrap will not be used as part of the installation of A. However,
because A's shrinkwrap is constructed from a valid installation of B
and recursively specifies all dependencies, the contents of B's
shrinkwrap will implicitly be included in A's shrinkwrap.</p>
<h3id="Caveats">Caveats</h3>
<h3id="caveats">Caveats</h3>
<p>Shrinkwrap files only lock down package versions, not actual package
contents. While discouraged, a package author can republish an
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
the shrinkwrap file to use git URL references rather than version
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
example to have 100% confidence in being able to reproduce a
deployment or build, then you ought to check your dependencies into
source control, or pursue some other mechanism that can verify
npm rm (with any of the previous argument usage)</code></pre>
<h2id="DESCRIPTION">DESCRIPTION</h2>
npm rm (with any of the previous argument usage)
</code></pre><h2id="description">DESCRIPTION</h2>
<p>This uninstalls a package, completely removing everything npm installed
on its behalf.</p>
<p>Example:</p>
<pre><code>npm uninstall sax</code></pre>
<p>In global mode (ie, with <code>-g</code> or <code>--global</code> appended to the command),
<pre><code>npm uninstall sax
</code></pre><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>
<p><code>npm uninstall</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 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>
<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
modules in place so that node can find them, and manages dependency
conflicts intelligently.</p>
<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
programs.</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>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>
<p>Use the <code>npm search</code> command to show everything that's available.
Use <code>npm ls</code> to show everything you've installed.</p>
<h2id="DIRECTORIES">DIRECTORIES</h2>
<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>In particular, npm has two modes of operation:</p>
<ul><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
<ul>
<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
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
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
following help topics:</p>
<ul><li>json:
Make a package.json file. See <code><ahref="../files/package.json.html">package.json(5)</a></code>.</li><li>link:
<ul>
<li>json:
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
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.
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
user config file.</li><li>publish:
Use the <code>npm publish</code> command to upload your code to the registry.</li></ul>
<h2id="CONFIGURATION">CONFIGURATION</h2>
user config file.</li>
<li>publish:
Use the <code>npm publish</code> command to upload your code to the registry.</li>
</ul>
<h2id="configuration">CONFIGURATION</h2>
<p>npm is extremely configurable. It reads its configuration options from
5 places.</p>
<ul><li>Command line switches:<br/>Set a config with <code>--key val</code>. All keys take a value, even if they
<ul>
<li>Command line switches:<br>Set a config with <code>--key val</code>. All keys take a value, even if they
are booleans (the config parser doesn't know what the options are at
the time of parsing.) If no value is provided, then the option is set
to boolean <code>true</code>.</li><li>Environment Variables:<br/>Set any config by prefixing the name in an environment variable with
<code>npm_config_</code>. For example, <code>export npm_config_key=val</code>.</li><li>User Configs:<br/>The file at $HOME/.npmrc is an ini-formatted list of configs. If
to boolean <code>true</code>.</li>
<li>Environment Variables:<br>Set any config by prefixing the name in an environment variable with
<code>npm_config_</code>. For example, <code>export npm_config_key=val</code>.</li>
<li>User Configs:<br>The file at $HOME/.npmrc is an ini-formatted list of configs. If
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.
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
lib/utils/config-defs.js. These must not be changed.</li></ul>
then that file is parsed instead.</li>
<li>Defaults:<br>npm's default configuration options are defined in
lib/utils/config-defs.js. These must not be changed.</li>
</ul>
<p>See <code><ahref="../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>
<ul><li>code:
<ul>
<li>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
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
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
<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>This document will tell you what it puts where.</p>
<h3id="tl-dr">tl;dr</h3>
<ul><li>Local install (default): puts stuff in <code>./node_modules</code> of the current
package root.</li><li>Global install (with <code>-g</code>): puts stuff in /usr/local or wherever node
is installed.</li><li>Install it <strong>locally</strong> if you're going to <code>require()</code> it.</li><li>Install it <strong>globally</strong> if you're going to run it on the command line.</li><li>If you need both, then install it in both places, or use <code>npm link</code>.</li></ul>
<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>This document will tell you what it puts where.</p>
<h3id="tl-dr">tl;dr</h3>
<ul><li>Local install (default): puts stuff in <code>./node_modules</code> of the current
package root.</li><li>Global install (with <code>-g</code>): puts stuff in /usr/local or wherever node
is installed.</li><li>Install it <strong>locally</strong> if you're going to <code>require()</code> it.</li><li>Install it <strong>globally</strong> if you're going to run it on the command line.</li><li>If you need both, then install it in both places, or use <code>npm link</code>.</li></ul>
</code></pre><p>and then had a "start" command that then referenced the
<code>npm_package_config_port</code> environment variable, then the user could
override that by doing <code>npm config set foo:port 8001</code>.</p>
<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>
<h2id="dependencies">dependencies</h2>
<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
space-separated descriptors. Dependencies can also be identified with
a tarball or git URL.</p>
<p><strong>Please do not put test harnesses or transpilers in your
<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>
<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>
<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>
</code></pre><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
installed globally, then set this value to <code>true</code> to provide a warning
if it is installed locally.</p>
<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>
<h2id="private">private</h2>
<p>If you set <code>"private": true</code> in your package.json, then npm will refuse
to publish it.</p>
<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
to a specific registry (for example, an internal registry),
then use the <code>publishConfig</code> hash described below
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
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
the global public registry by default.</p>
<p>Any config values can be overridden, but of course only "tag" and
"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
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>
<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
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
</code></pre><p>and then had a "start" command that then referenced the
<code>npm_package_config_port</code> environment variable, then the user could
override that by doing <code>npm config set foo:port 8001</code>.</p>
<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>
<h2id="dependencies">dependencies</h2>
<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
space-separated descriptors. Dependencies can also be identified with
a tarball or git URL.</p>
<p><strong>Please do not put test harnesses or transpilers in your
<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>
<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>
<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>
</code></pre><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
installed globally, then set this value to <code>true</code> to provide a warning
if it is installed locally.</p>
<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>
<h2id="private">private</h2>
<p>If you set <code>"private": true</code> in your package.json, then npm will refuse
to publish it.</p>
<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
to a specific registry (for example, an internal registry),
then use the <code>publishConfig</code> hash described below
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
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
the global public registry by default.</p>
<p>Any config values can be overridden, but of course only "tag" and
"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
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>
<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
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
<p>npm's coding style is a bit unconventional. It is not different for
difference's sake, but rather a carefully crafted style that is
designed to reduce visual clutter and make bugs more apparent.</p>
<p>If you want to contribute to npm (which is very encouraged), you should
make your code conform to npm's style.</p>
<p>Note: this concerns npm's code not the specific packages at npmjs.org</p>
<h2id="Line-Length">Line Length</h2>
<h2id="line-length">Line Length</h2>
<p>Keep lines shorter than 80 characters. It's better for lines to be
too short than to be too long. Break up long lists, objects, and other
statements onto multiple lines.</p>
<h2id="Indentation">Indentation</h2>
<h2id="indentation">Indentation</h2>
<p>Two-spaces. Tabs are better, but they look like hell in web browsers
(and on github), and node uses 2 spaces, so that's that.</p>
<p>Configure your editor appropriately.</p>
<h2id="Curly-braces">Curly braces</h2>
<h2id="curly-braces">Curly braces</h2>
<p>Curly braces belong on the same line as the thing that necessitates them.</p>
<p>Bad:</p>
<pre><code>function ()
{</code></pre>
<p>Good:</p>
<pre><code>function () {</code></pre>
<p>If a block needs to wrap to the next line, use a curly brace. Don't
{
</code></pre><p>Good:</p>
<pre><code>function () {
</code></pre><p>If a block needs to wrap to the next line, use a curly brace. Don't
use it if it doesn't.</p>
<p>Bad:</p>
<pre><code>if (foo) { bar() }
while (foo)
bar()</code></pre>
<p>Good:</p>
bar()
</code></pre><p>Good:</p>
<pre><code>if (foo) bar()
while (foo) {
bar()
}</code></pre>
<h2id="Semicolons">Semicolons</h2>
}
</code></pre><h2id="semicolons">Semicolons</h2>
<p>Don't use them except in four situations:</p>
<ul><li><code>for (;;)</code> loops. They're actually required.</li><li>null loops like: <code>while (something) ;</code> (But you'd better have a good
reason for doing that.)</li><li><code>case "foo": doSomething(); break</code></li><li>In front of a leading <code>(</code> or <code>[</code> at the start of the line.
<p>So, you've decided to use npm to develop (and maybe publish/deploy)
your project.</p>
<p>Fantastic!</p>
<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>
<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
then do <code>man npm-thing</code> to get the documentation on a particular
topic, or <code>npm help thing</code> to see the same information.</p>
<h2id="What-is-a-package">What is a <code>package</code></h2>
<h2id="what-is-a-package-">What is a <code>package</code></h2>
<p>A package is:</p>
<ul><li>a) a folder containing a program described by a package.json file</li><li>b) a gzipped tarball containing (a)</li><li>c) a url that resolves to (b)</li><li>d) a <code><name>@<version></code> that is published on the registry with (c)</li><li>e) a <code><name>@<tag></code> that points to (d)</li><li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li><li>g) a <code>git</code> url that, when cloned, results in (a).</li></ul>
<ul>
<li>a) a folder containing a program described by a package.json file</li>
<li>b) a gzipped tarball containing (a)</li>
<li>c) a url that resolves to (b)</li>
<li>d) a <code><name>@<version></code> that is published on the registry with (c)</li>
<li>e) a <code><name>@<tag></code> that points to (d)</li>
<li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li>
<li>g) a <code>git</code> url that, when cloned, results in (a).</li>
</ul>
<p>Even if you never publish your package, you can still get a lot of
benefits of using npm if you just want to write a node program (a), and
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
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
least, you need:</p>
<ul><li><p>name:
<ul>
<li><p>name:
This should be a string that identifies your project. Please do not
use the name to specify that it runs on node, or is in JavaScript.
You can use the "engines" field to explicitly state the versions of
node (or whatever else) that your program requires, and it's pretty
well assumed that it's javascript.</p><p>It does not necessarily need to match your github repository name.</p><p>So, <code>node-foo</code> and <code>bar-js</code> are bad names. <code>foo</code> or <code>bar</code> are better.</p></li><li><p>version:
A semver-compatible version.</p></li><li><p>engines:
well assumed that it's javascript.</p>
<p>It does not necessarily need to match your github repository name.</p>
<p>So, <code>node-foo</code> and <code>bar-js</code> are bad names. <code>foo</code> or <code>bar</code> are better.</p>
</li>
<li><p>version:
A semver-compatible version.</p>
</li>
<li><p>engines:
Specify the versions of node (or whatever else) that your program
runs on. The node API changes a lot, and there may be bugs or new
functionality that you depend on. Be explicit.</p></li><li><p>author:
Take some credit.</p></li><li><p>scripts:
functionality that you depend on. Be explicit.</p>
</li>
<li><p>author:
Take some credit.</p>
</li>
<li><p>scripts:
If you have a special compilation or installation script, then you
should put it in the <code>scripts</code> hash. You should definitely have at
least a basic smoke-test command as the "scripts.test" field.
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
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
"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
started with a pretty basic package.json file. See <code><ahref="../cli/npm-init.html">npm-init(1)</a></code> for
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
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
include something that is excluded by your <code>.gitignore</code> file, you can
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
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>
<h2id="SYNOPSIS">SYNOPSIS</h2>
<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>
<h2id="synopsis">SYNOPSIS</h2>
<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>
<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
later, some other user wants to use that name. Here are some common
ways that happens (each of these is based on actual events.)</p>
<ol><li>Joe writes a JavaScript module <code>foo</code>, which is not node-specific.
<ol>
<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
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
request to Bob, but Bob doesn't have the time to deal with it,
because he has a new job and a new baby and is focused on his new
erlang project, and kind of not involved with node any more. Joe
would like to publish a new <code>foo</code>, but can't, because the name is
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
never really has to be updated. Joe works for Foo Inc, the makers
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
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
prototype. Later on, Joe writes a much more complete <code>foo</code> parser,
but can't publish, because Bob's <code>foo</code> is in the way.</li></ol>
but can't publish, because Bob's <code>foo</code> is in the way.</li>
</ol>
<p>The validity of Joe's claim in each situation can be debated. However,
Joe's appropriate course of action in each case is the same.</p>
<ol><li><code>npm owner ls foo</code>. This will tell Joe the email address of the
owner (Bob).</li><li>Joe emails Bob, explaining the situation <strong>as respectfully as
<ol>
<li><code>npm owner ls foo</code>. This will tell Joe the email address of the
owner (Bob).</li>
<li>Joe emails Bob, explaining the situation <strong>as respectfully as
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
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
<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
holidays.)</li></ol>
<h2id="REASONING">REASONING</h2>
holidays.)</li>
</ol>
<h2id="reasoning">REASONING</h2>
<p>In almost every case so far, the parties involved have been able to reach
an amicable resolution without any major intervention. Most people
really do want to be reasonable, and are probably not even aware that
they're in your way.</p>
<p>Module ecosystems are most vibrant and powerful when they are as
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,
regardless of the justification. When humans solve their problems by
talking to other humans with respect, everyone has the chance to end up
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
they are brought to the attention of the npm registry admins, including
but not limited to:</p>
<ol><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
<ol>
<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
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
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
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
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
things into it.</li></ol>
things into it.</li>
</ol>
<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>
command to see where executables go</li><li>Global installs are different from local installs. If you install
<ul>
<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
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>
<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>
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>
<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
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>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>
<p>If you <code>require()</code> a module in your code, then that means it's a
dependency, and a part of your program. You need to install it locally
in your program.</p>
<h2id="Why-can-t-npm-just-put-everything-in-one-place-like-other-package-managers">Why can't npm just put everything in one place, like other package managers?</h2>
<h2id="why-can-t-npm-just-put-everything-in-one-place-like-other-package-managers-">Why can't npm just put everything in one place, like other package managers?</h2>
<p>Not every change is an improvement, but every improvement is a change.
This would be like asking git to do network IO for every commit. It's
not going to happen, because it's a terrible idea that causes more
problems than it solves.</p>
<p>It is much harder to avoid dependency conflicts without nesting
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
more details.</p>
<p>If you want a package to be installed in one place, and have all your
programs reference the same copy of it, then use the <code>npm link</code> command.
That's what it's for. Install it globally, then link it into each
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>
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>
<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>
<h2id="What-is-a-package">What is a <code>package</code>?</h2>
<pre><code>curl https://www.npmjs.org/install.sh | sh
</code></pre><h2id="what-is-a-package-">What is a <code>package</code>?</h2>
<p>A package is:</p>
<ul><li>a) a folder containing a program described by a package.json file</li><li>b) a gzipped tarball containing (a)</li><li>c) a url that resolves to (b)</li><li>d) a <code><name>@<version></code> that is published on the registry with (c)</li><li>e) a <code><name>@<tag></code> that points to (d)</li><li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li><li>g) a <code>git</code> url that, when cloned, results in (a).</li></ul>
<ul>
<li>a) a folder containing a program described by a package.json file</li>
<li>b) a gzipped tarball containing (a)</li>
<li>c) a url that resolves to (b)</li>
<li>d) a <code><name>@<version></code> that is published on the registry with (c)</li>
<li>e) a <code><name>@<tag></code> that points to (d)</li>
<li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li>
<li>g) a <code>git</code> url that, when cloned, results in (a).</li>
</ul>
<p>Even if you never publish your package, you can still get a lot of
benefits of using npm if you just want to write a node program (a), and
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
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
program. The following things are all examples of things that can be
loaded as modules:</p>
<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>
<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
load with <code>require</code>. However, there's no requirement that an npm
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>
<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
<code>require()</code> is a module).</p>
<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>
<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>
<pre><code>var req = require('request')
</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>The <code>package.json</code> file defines the package. (See "What is a
package?" above.)</p>
<p>The <code>node_modules</code> folder is the place Node.js looks for modules.
(See "What is a module?" above.)</p>
<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
the module. However, <code>foo.js</code> is not a "package" in this case,
because it does not have a package.json.</p>
<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
not a module. Even if it's installed in <code>node_modules</code>, it can't be
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,
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
from there. It's an arbitrary spelling choice, right? What's the big
deal?</p>
<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
documentation).</p>
<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
be configured to know where you've decided to stick stuff. Complexity
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
deference to your deity's delicate feelings regarding spelling.</p>
<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
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
parameter. Complexity hurdle #2.</p>
<p>Furthermore, npm has the ability to "bundle" dependencies by adding
the dep names to the <code>"bundledDependencies"</code> list in package.json,
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
folder at publish time, and then be smart enough to unpack it using
your locally configured name. Complexity hurdle #3.</p>
<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
<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
config, and always accept any of them, or else yesterday's install may
be broken tomorrow. Complexity hurdle #5.</p>
<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
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>
<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>You'll most likely want to <code>npm link</code> your development folder. That's
awesomely handy.</p>
<p>To set up your own private registry, check out <code><ahref="../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
that has a package.json in its root, or a git url.
(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>
<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>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
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
down for the world (and not just on your local network) then we're
probably already being pinged about it.</p>
<p>You can also often get a faster response by visiting the #npm channel
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>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
<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>
<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
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
website</a> are maintained and operated by the
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