<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>
Fedor Indutny
11 years ago