mirror of https://github.com/lukechilds/node.git
isaacs
12 years ago
1823 changed files with 32757 additions and 79309 deletions
@ -1,22 +0,0 @@ |
|||
npm-commands(3) -- npm commands |
|||
=============================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm.commands[<command>](args, callback) |
|||
|
|||
## DESCRIPTION |
|||
|
|||
npm comes with a full set of commands, and each of the commands takes a |
|||
similar set of arguments. |
|||
|
|||
In general, all commands on the command object take an **array** of positional |
|||
argument **strings**. The last argument to any function is a callback. Some |
|||
commands are special and take other optional arguments. |
|||
|
|||
All commands have their own man page. See `man npm-<command>` for command-line |
|||
usage, or `man 3 npm-<command>` for programmatic usage. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-index(1) |
|||
@ -1,34 +0,0 @@ |
|||
npm-deprecate(3) -- Deprecate a version of a package |
|||
==================================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm.commands.deprecate(args, callback) |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This command will update the npm registry entry for a package, providing |
|||
a deprecation warning to all who attempt to install it. |
|||
|
|||
The 'args' parameter must have exactly two elements: |
|||
|
|||
* `package[@version]` |
|||
|
|||
The `version` portion is optional, and may be either a range, or a |
|||
specific version, or a tag. |
|||
|
|||
* `message` |
|||
|
|||
The warning message that will be printed whenever a user attempts to |
|||
install the package. |
|||
|
|||
Note that you must be the package owner to deprecate something. See the |
|||
`owner` and `adduser` help topics. |
|||
|
|||
To un-deprecate a package, specify an empty string (`""`) for the `message` argument. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-publish(3) |
|||
* npm-unpublish(3) |
|||
* npm-registry(1) |
|||
@ -1,29 +0,0 @@ |
|||
npm init(3) -- Interactively create a package.json file |
|||
======================================================= |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm.commands.init(args, callback) |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This will ask you a bunch of questions, and then write a package.json for you. |
|||
|
|||
It attempts to make reasonable guesses about what you want things to be set to, |
|||
and then writes a package.json file with the options you've selected. |
|||
|
|||
If you already have a package.json file, it'll read that first, and default to |
|||
the options in there. |
|||
|
|||
It is strictly additive, so it does not delete options from your package.json |
|||
without a really good reason to do so. |
|||
|
|||
Since this function expects to be run on the command-line, it doesn't work very |
|||
well as a programmatically. The best option is to roll your own, and since |
|||
JavaScript makes it stupid simple to output formatted JSON, that is the |
|||
preferred method. If you're sure you want to handle command-line prompting, |
|||
then go ahead and use this programmatically. |
|||
|
|||
## SEE ALSO |
|||
|
|||
npm-json(1) |
|||
@ -0,0 +1,22 @@ |
|||
npm-commands(3) -- npm commands |
|||
=============================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm.commands[<command>](args, callback) |
|||
|
|||
## DESCRIPTION |
|||
|
|||
npm comes with a full set of commands, and each of the commands takes a |
|||
similar set of arguments. |
|||
|
|||
In general, all commands on the command object take an **array** of positional |
|||
argument **strings**. The last argument to any function is a callback. Some |
|||
commands are special and take other optional arguments. |
|||
|
|||
All commands have their own man page. See `man npm-<command>` for command-line |
|||
usage, or `man 3 npm-<command>` for programmatic usage. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-index(7) |
|||
@ -0,0 +1,34 @@ |
|||
npm-deprecate(3) -- Deprecate a version of a package |
|||
==================================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm.commands.deprecate(args, callback) |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This command will update the npm registry entry for a package, providing |
|||
a deprecation warning to all who attempt to install it. |
|||
|
|||
The 'args' parameter must have exactly two elements: |
|||
|
|||
* `package[@version]` |
|||
|
|||
The `version` portion is optional, and may be either a range, or a |
|||
specific version, or a tag. |
|||
|
|||
* `message` |
|||
|
|||
The warning message that will be printed whenever a user attempts to |
|||
install the package. |
|||
|
|||
Note that you must be the package owner to deprecate something. See the |
|||
`owner` and `adduser` help topics. |
|||
|
|||
To un-deprecate a package, specify an empty string (`""`) for the `message` argument. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-publish(3) |
|||
* npm-unpublish(3) |
|||
* npm-registry(7) |
|||
@ -0,0 +1,29 @@ |
|||
npm init(3) -- Interactively create a package.json file |
|||
======================================================= |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm.commands.init(args, callback) |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This will ask you a bunch of questions, and then write a package.json for you. |
|||
|
|||
It attempts to make reasonable guesses about what you want things to be set to, |
|||
and then writes a package.json file with the options you've selected. |
|||
|
|||
If you already have a package.json file, it'll read that first, and default to |
|||
the options in there. |
|||
|
|||
It is strictly additive, so it does not delete options from your package.json |
|||
without a really good reason to do so. |
|||
|
|||
Since this function expects to be run on the command-line, it doesn't work very |
|||
well as a programmatically. The best option is to roll your own, and since |
|||
JavaScript makes it stupid simple to output formatted JSON, that is the |
|||
preferred method. If you're sure you want to handle command-line prompting, |
|||
then go ahead and use this programmatically. |
|||
|
|||
## SEE ALSO |
|||
|
|||
package.json(5) |
|||
@ -0,0 +1,31 @@ |
|||
npm-owner(3) -- Manage package owners |
|||
===================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm.commands.owner(args, callback) |
|||
|
|||
## DESCRIPTION |
|||
|
|||
The first element of the 'args' parameter defines what to do, and the subsequent |
|||
elements depend on the action. Possible values for the action are (order of |
|||
parameters are given in parenthesis): |
|||
|
|||
* ls (package): |
|||
List all the users who have access to modify a package and push new versions. |
|||
Handy when you need to know who to bug for help. |
|||
* add (user, package): |
|||
Add a new user as a maintainer of a package. This user is enabled to modify |
|||
metadata, publish new versions, and add other owners. |
|||
* rm (user, package): |
|||
Remove a user from the package owner list. This immediately revokes their |
|||
privileges. |
|||
|
|||
Note that there is only one level of access. Either you can modify a package, |
|||
or you can't. Future versions may contain more fine-grained access levels, but |
|||
that is not implemented at this time. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-publish(3) |
|||
* npm-registry(7) |
|||
@ -0,0 +1,30 @@ |
|||
npm-publish(3) -- Publish a package |
|||
=================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm.commands.publish([packages,] callback) |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Publishes a package to the registry so that it can be installed by name. |
|||
Possible values in the 'packages' array are: |
|||
|
|||
* `<folder>`: |
|||
A folder containing a package.json file |
|||
|
|||
* `<tarball>`: |
|||
A url or file path to a gzipped tar archive containing a single folder |
|||
with a package.json file inside. |
|||
|
|||
If the package array is empty, npm will try to publish something in the |
|||
current working directory. |
|||
|
|||
This command could fails if one of the packages specified already exists in |
|||
the registry. Overwrites when the "force" environment variable is set. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-registry(7) |
|||
* npm-adduser(1) |
|||
* npm-owner(3) |
|||
@ -0,0 +1,27 @@ |
|||
npm-run-script(3) -- Run arbitrary package scripts |
|||
================================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm.commands.run-script(args, callback) |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This runs an arbitrary command from a package's "scripts" object. |
|||
|
|||
It is used by the test, start, restart, and stop commands, but can be |
|||
called directly, as well. |
|||
|
|||
The 'args' parameter is an array of strings. Behavior depends on the number |
|||
of elements. If there is only one element, npm assumes that the element |
|||
represents a command to be run on the local repository. If there is more than |
|||
one element, then the first is assumed to be the package and the second is |
|||
assumed to be the command to run. All other elements are ignored. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-scripts(7) |
|||
* npm-test(3) |
|||
* npm-start(3) |
|||
* npm-restart(3) |
|||
* npm-stop(3) |
|||
@ -1,31 +0,0 @@ |
|||
npm-owner(3) -- Manage package owners |
|||
===================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm.commands.owner(args, callback) |
|||
|
|||
## DESCRIPTION |
|||
|
|||
The first element of the 'args' parameter defines what to do, and the subsequent |
|||
elements depend on the action. Possible values for the action are (order of |
|||
parameters are given in parenthesis): |
|||
|
|||
* ls (package): |
|||
List all the users who have access to modify a package and push new versions. |
|||
Handy when you need to know who to bug for help. |
|||
* add (user, package): |
|||
Add a new user as a maintainer of a package. This user is enabled to modify |
|||
metadata, publish new versions, and add other owners. |
|||
* rm (user, package): |
|||
Remove a user from the package owner list. This immediately revokes their |
|||
privileges. |
|||
|
|||
Note that there is only one level of access. Either you can modify a package, |
|||
or you can't. Future versions may contain more fine-grained access levels, but |
|||
that is not implemented at this time. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-publish(3) |
|||
* npm-registry(1) |
|||
@ -1,30 +0,0 @@ |
|||
npm-publish(3) -- Publish a package |
|||
=================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm.commands.publish([packages,] callback) |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Publishes a package to the registry so that it can be installed by name. |
|||
Possible values in the 'packages' array are: |
|||
|
|||
* `<folder>`: |
|||
A folder containing a package.json file |
|||
|
|||
* `<tarball>`: |
|||
A url or file path to a gzipped tar archive containing a single folder |
|||
with a package.json file inside. |
|||
|
|||
If the package array is empty, npm will try to publish something in the |
|||
current working directory. |
|||
|
|||
This command could fails if one of the packages specified already exists in |
|||
the registry. Overwrites when the "force" environment variable is set. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-registry(1) |
|||
* npm-adduser(1) |
|||
* npm-owner(3) |
|||
@ -1,27 +0,0 @@ |
|||
npm-run-script(3) -- Run arbitrary package scripts |
|||
================================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm.commands.run-script(args, callback) |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This runs an arbitrary command from a package's "scripts" object. |
|||
|
|||
It is used by the test, start, restart, and stop commands, but can be |
|||
called directly, as well. |
|||
|
|||
The 'args' parameter is an array of strings. Behavior depends on the number |
|||
of elements. If there is only one element, npm assumes that the element |
|||
represents a command to be run on the local repository. If there is more than |
|||
one element, then the first is assumed to be the package and the second is |
|||
assumed to be the command to run. All other elements are ignored. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-scripts(1) |
|||
* npm-test(3) |
|||
* npm-start(3) |
|||
* npm-restart(3) |
|||
* npm-stop(3) |
|||
@ -1,36 +0,0 @@ |
|||
npm-adduser(1) -- Add a registry user account |
|||
============================================= |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm adduser |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Create or verify a user named `<username>` in the npm registry, and |
|||
save the credentials to the `.npmrc` file. |
|||
|
|||
The username, password, and email are read in from prompts. |
|||
|
|||
You may use this command to change your email address, but not username |
|||
or password. |
|||
|
|||
To reset your password, go to <http://admin.npmjs.org/> |
|||
|
|||
You may use this command multiple times with the same user account to |
|||
authorize on a new machine. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### registry |
|||
|
|||
Default: http://registry.npmjs.org/ |
|||
|
|||
The base URL of the npm package registry. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-registry(1) |
|||
* npm-config(1) |
|||
* npm-owner(1) |
|||
* npm-whoami(1) |
|||
@ -1,17 +0,0 @@ |
|||
npm-bin(1) -- Display npm bin folder |
|||
==================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm bin |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Print the folder where npm will install executables. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-prefix(1) |
|||
* npm-root(1) |
|||
* npm-folders(1) |
|||
* npm-config(1) |
|||
@ -1,38 +0,0 @@ |
|||
npm-bugs(1) -- Bugs for a package in a web browser maybe |
|||
======================================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm bugs <pkgname> |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This command tries to guess at the likely location of a package's |
|||
bug tracker URL, and then tries to open it using the `--browser` |
|||
config param. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### browser |
|||
|
|||
* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` |
|||
* Type: String |
|||
|
|||
The browser that is called by the `npm bugs` command to open websites. |
|||
|
|||
### registry |
|||
|
|||
* Default: https://registry.npmjs.org/ |
|||
* Type: url |
|||
|
|||
The base URL of the npm package registry. |
|||
|
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-docs(1) |
|||
* npm-view(1) |
|||
* npm-publish(1) |
|||
* npm-registry(1) |
|||
* npm-config(1) |
|||
* npm-json(1) |
|||
@ -1,22 +0,0 @@ |
|||
npm-build(1) -- Build a package |
|||
=============================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm build <package-folder> |
|||
|
|||
* `<package-folder>`: |
|||
A folder containing a `package.json` file in its root. |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This is the plumbing command called by `npm link` and `npm install`. |
|||
|
|||
It should generally not be called directly. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-install(1) |
|||
* npm-link(1) |
|||
* npm-scripts(1) |
|||
* npm-json(1) |
|||
@ -1,70 +0,0 @@ |
|||
npm-cache(1) -- Manipulates packages cache |
|||
========================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm cache add <tarball file> |
|||
npm cache add <folder> |
|||
npm cache add <tarball url> |
|||
npm cache add <name>@<version> |
|||
|
|||
npm cache ls [<path>] |
|||
|
|||
npm cache clean [<path>] |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Used to add, list, or clear the npm cache folder. |
|||
|
|||
* add: |
|||
Add the specified package to the local cache. This command is primarily |
|||
intended to be used internally by npm, but it can provide a way to |
|||
add data to the local installation cache explicitly. |
|||
|
|||
* ls: |
|||
Show the data in the cache. Argument is a path to show in the cache |
|||
folder. Works a bit like the `find` program, but limited by the |
|||
`depth` config. |
|||
|
|||
* clean: |
|||
Delete data out of the cache folder. If an argument is provided, then |
|||
it specifies a subpath to delete. If no argument is provided, then |
|||
the entire cache is cleared. |
|||
|
|||
## DETAILS |
|||
|
|||
npm stores cache data in `$HOME/.npm`. For each package that is added |
|||
to the cache, three pieces of information are stored in |
|||
`{cache}/{name}/{version}`: |
|||
|
|||
* .../package/: |
|||
A folder containing the package contents as they appear in the tarball. |
|||
* .../package.json: |
|||
The package.json file, as npm sees it, with overlays applied and a _id attribute. |
|||
* .../package.tgz: |
|||
The tarball for that version. |
|||
|
|||
Additionally, whenever a registry request is made, a `.cache.json` file |
|||
is placed at the corresponding URI, to store the ETag and the requested |
|||
data. |
|||
|
|||
Commands that make non-essential registry requests (such as `search` and |
|||
`view`, or the completion scripts) generally specify a minimum timeout. |
|||
If the `.cache.json` file is younger than the specified timeout, then |
|||
they do not make an HTTP request to the registry. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### cache |
|||
|
|||
Default: `$HOME/.npm` on Posix, or `$HOME/npm-cache` on Windows. |
|||
|
|||
The root cache folder. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-folders(1) |
|||
* npm-config(1) |
|||
* npm-install(1) |
|||
* npm-publish(1) |
|||
* npm-pack(1) |
|||
@ -1,80 +0,0 @@ |
|||
npm-changelog(1) -- Changes |
|||
=========================== |
|||
|
|||
## HISTORY |
|||
|
|||
### 1.1.3, 1.1.4 |
|||
|
|||
* Update request to support HTTPS-over-HTTP proxy tunneling |
|||
* Throw on undefined envs in config settings |
|||
* Update which to 1.0.5 |
|||
* Fix windows UNC busyloop in findPrefix |
|||
* Bundle nested bundleDependencies properly |
|||
* Alias adduser to add-user |
|||
* Doc updates (Christian Howe, Henrik Hodne, Andrew Lunny) |
|||
* ignore logfd/outfd streams in makeEnv() (Rod Vagg) |
|||
* shrinkwrap: Behave properly with url-installed deps |
|||
* install: Support --save with url install targets |
|||
* Support installing naked tars or single-file modules from urls etc. |
|||
* init: Don't add engines section |
|||
* Don't run make clean on rebuild |
|||
* Added missing unicode replacement (atomizer) |
|||
|
|||
### 1.1.2 |
|||
|
|||
Dave Pacheco (2): |
|||
add "npm shrinkwrap" |
|||
|
|||
Martin Cooper (1): |
|||
Fix #1753 Make a copy of the cached objects we'll modify. |
|||
|
|||
Tim Oxley (1): |
|||
correctly remove readme from default npm view command. |
|||
|
|||
Tyler Green (1): |
|||
fix #2187 set terminal columns to Infinity if 0 |
|||
|
|||
isaacs (19): |
|||
update minimatch |
|||
update request |
|||
Experimental: single-file modules |
|||
Fix #2172 Don't remove global mans uninstalling local pkgs |
|||
Add --versions flag to show the version of node as well |
|||
Support --json flag for ls output |
|||
update request to 2.9.151 |
|||
|
|||
### 1.1 |
|||
* Replace system tar dependency with a JS tar |
|||
* Continue to refine |
|||
|
|||
### 1.0 |
|||
* Greatly simplified folder structure |
|||
* Install locally (bundle by default) |
|||
* Drastic rearchitecture |
|||
|
|||
### 0.3 |
|||
* More correct permission/uid handling when running as root |
|||
* Require node 0.4.0 |
|||
* Reduce featureset |
|||
* Packages without "main" modules don't export modules |
|||
* Remove support for invalid JSON (since node doesn't support it) |
|||
|
|||
### 0.2 |
|||
* First allegedly "stable" release |
|||
* Most functionality implemented |
|||
* Used shim files and `name@version` symlinks |
|||
* Feature explosion |
|||
* Kind of a mess |
|||
|
|||
### 0.1 |
|||
* push to beta, and announce |
|||
* Solaris and Cygwin support |
|||
|
|||
### 0.0 |
|||
* Lots of sketches and false starts; abandoned a few times |
|||
* Core functionality established |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm(1) |
|||
* npm-faq(1) |
|||
@ -1,181 +0,0 @@ |
|||
npm-coding-style(1) -- npm's "funny" coding style |
|||
================================================= |
|||
|
|||
## DESCRIPTION |
|||
|
|||
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. |
|||
|
|||
If you want to contribute to npm (which is very encouraged), you should |
|||
make your code conform to npm's style. |
|||
|
|||
Note: this concerns npm's code not the specific packages at npmjs.org |
|||
|
|||
## Line Length |
|||
|
|||
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. |
|||
|
|||
## Indentation |
|||
|
|||
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. |
|||
|
|||
Configure your editor appropriately. |
|||
|
|||
## Curly braces |
|||
|
|||
Curly braces belong on the same line as the thing that necessitates them. |
|||
|
|||
Bad: |
|||
|
|||
function () |
|||
{ |
|||
|
|||
Good: |
|||
|
|||
function () { |
|||
|
|||
If a block needs to wrap to the next line, use a curly brace. Don't |
|||
use it if it doesn't. |
|||
|
|||
Bad: |
|||
|
|||
if (foo) { bar() } |
|||
while (foo) |
|||
bar() |
|||
|
|||
Good: |
|||
|
|||
if (foo) bar() |
|||
while (foo) { |
|||
bar() |
|||
} |
|||
|
|||
## Semicolons |
|||
|
|||
Don't use them except in four situations: |
|||
|
|||
* `for (;;)` loops. They're actually required. |
|||
* null loops like: `while (something) ;` (But you'd better have a good |
|||
reason for doing that.) |
|||
* `case "foo": doSomething(); break` |
|||
* In front of a leading `(` or `[` at the start of the line. |
|||
This prevents the expression from being interpreted |
|||
as a function call or property access, respectively. |
|||
|
|||
Some examples of good semicolon usage: |
|||
|
|||
;(x || y).doSomething() |
|||
;[a, b, c].forEach(doSomething) |
|||
for (var i = 0; i < 10; i ++) { |
|||
switch (state) { |
|||
case "begin": start(); continue |
|||
case "end": finish(); break |
|||
default: throw new Error("unknown state") |
|||
} |
|||
end() |
|||
} |
|||
|
|||
Note that starting lines with `-` and `+` also should be prefixed |
|||
with a semicolon, but this is much less common. |
|||
|
|||
## Comma First |
|||
|
|||
If there is a list of things separated by commas, and it wraps |
|||
across multiple lines, put the comma at the start of the next |
|||
line, directly below the token that starts the list. Put the |
|||
final token in the list on a line by itself. For example: |
|||
|
|||
var magicWords = [ "abracadabra" |
|||
, "gesundheit" |
|||
, "ventrilo" |
|||
] |
|||
, spells = { "fireball" : function () { setOnFire() } |
|||
, "water" : function () { putOut() } |
|||
} |
|||
, a = 1 |
|||
, b = "abc" |
|||
, etc |
|||
, somethingElse |
|||
|
|||
## Whitespace |
|||
|
|||
Put a single space in front of ( for anything other than a function call. |
|||
Also use a single space wherever it makes things more readable. |
|||
|
|||
Don't leave trailing whitespace at the end of lines. Don't indent empty |
|||
lines. Don't use more spaces than are helpful. |
|||
|
|||
## Functions |
|||
|
|||
Use named functions. They make stack traces a lot easier to read. |
|||
|
|||
## Callbacks, Sync/async Style |
|||
|
|||
Use the asynchronous/non-blocking versions of things as much as possible. |
|||
It might make more sense for npm to use the synchronous fs APIs, but this |
|||
way, the fs and http and child process stuff all uses the same callback-passing |
|||
methodology. |
|||
|
|||
The callback should always be the last argument in the list. Its first |
|||
argument is the Error or null. |
|||
|
|||
Be very careful never to ever ever throw anything. It's worse than useless. |
|||
Just send the error message back as the first argument to the callback. |
|||
|
|||
## Errors |
|||
|
|||
Always create a new Error object with your message. Don't just return a |
|||
string message to the callback. Stack traces are handy. |
|||
|
|||
## Logging |
|||
|
|||
Logging is done using the [npmlog](https://github.com/isaacs/npmlog) |
|||
utility. |
|||
|
|||
Please clean up logs when they are no longer helpful. In particular, |
|||
logging the same object over and over again is not helpful. Logs should |
|||
report what's happening so that it's easier to track down where a fault |
|||
occurs. |
|||
|
|||
Use appropriate log levels. See `npm-config(1)` and search for |
|||
"loglevel". |
|||
|
|||
## Case, naming, etc. |
|||
|
|||
Use `lowerCamelCase` for multiword identifiers when they refer to objects, |
|||
functions, methods, members, or anything not specified in this section. |
|||
|
|||
Use `UpperCamelCase` for class names (things that you'd pass to "new"). |
|||
|
|||
Use `all-lower-hyphen-css-case` for multiword filenames and config keys. |
|||
|
|||
Use named functions. They make stack traces easier to follow. |
|||
|
|||
Use `CAPS_SNAKE_CASE` for constants, things that should never change |
|||
and are rarely used. |
|||
|
|||
Use a single uppercase letter for function names where the function |
|||
would normally be anonymous, but needs to call itself recursively. It |
|||
makes it clear that it's a "throwaway" function. |
|||
|
|||
## null, undefined, false, 0 |
|||
|
|||
Boolean variables and functions should always be either `true` or |
|||
`false`. Don't set it to 0 unless it's supposed to be a number. |
|||
|
|||
When something is intentionally missing or removed, set it to `null`. |
|||
|
|||
Don't set things to `undefined`. Reserve that value to mean "not yet |
|||
set to anything." |
|||
|
|||
Boolean objects are verboten. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-developers(1) |
|||
* npm-faq(1) |
|||
* npm(1) |
|||
@ -1,29 +0,0 @@ |
|||
npm-completion(1) -- Tab Completion for npm |
|||
=========================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
. <(npm completion) |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Enables tab-completion in all npm commands. |
|||
|
|||
The synopsis above |
|||
loads the completions into your current shell. Adding it to |
|||
your ~/.bashrc or ~/.zshrc will make the completions available |
|||
everywhere. |
|||
|
|||
You may of course also pipe the output of npm completion to a file |
|||
such as `/usr/local/etc/bash_completion.d/npm` if you have a system |
|||
that will read that file for you. |
|||
|
|||
When `COMP_CWORD`, `COMP_LINE`, and `COMP_POINT` are defined in the |
|||
environment, `npm completion` acts in "plumbing mode", and outputs |
|||
completions based on the arguments. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-developers(1) |
|||
* npm-faq(1) |
|||
* npm(1) |
|||
@ -1,882 +0,0 @@ |
|||
npm-config(1) -- Manage the npm configuration file |
|||
================================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm config set <key> <value> [--global] |
|||
npm config get <key> |
|||
npm config delete <key> |
|||
npm config list |
|||
npm config edit |
|||
npm get <key> |
|||
npm set <key> <value> [--global] |
|||
|
|||
## DESCRIPTION |
|||
|
|||
npm gets its configuration values from 6 sources, in this priority: |
|||
|
|||
### Command Line Flags |
|||
|
|||
Putting `--foo bar` on the command line sets the |
|||
`foo` configuration parameter to `"bar"`. A `--` argument tells the cli |
|||
parser to stop reading flags. A `--flag` parameter that is at the *end* of |
|||
the command will be given the value of `true`. |
|||
|
|||
### Environment Variables |
|||
|
|||
Any environment variables that start with `npm_config_` will be interpreted |
|||
as a configuration parameter. For example, putting `npm_config_foo=bar` in |
|||
your environment will set the `foo` configuration parameter to `bar`. Any |
|||
environment configurations that are not given a value will be given the value |
|||
of `true`. Config values are case-insensitive, so `NPM_CONFIG_FOO=bar` will |
|||
work the same. |
|||
|
|||
### Per-user config file |
|||
|
|||
`$HOME/.npmrc` (or the `userconfig` param, if set above) |
|||
|
|||
This file is an ini-file formatted list of `key = value` parameters. |
|||
Environment variables can be replaced using `${VARIABLE_NAME}`. For example: |
|||
|
|||
prefix = ${HOME}/.npm-packages |
|||
|
|||
### Global config file |
|||
|
|||
`$PREFIX/etc/npmrc` (or the `globalconfig` param, if set above): |
|||
This file is an ini-file formatted list of `key = value` parameters. |
|||
Environment variables can be replaced as above. |
|||
|
|||
### Built-in config file |
|||
|
|||
`path/to/npm/itself/npmrc` |
|||
|
|||
This is an unchangeable "builtin" |
|||
configuration file that npm keeps consistent across updates. Set |
|||
fields in here using the `./configure` script that comes with npm. |
|||
This is primarily for distribution maintainers to override default |
|||
configs in a standard and consistent manner. |
|||
|
|||
### Default Configs |
|||
|
|||
A set of configuration parameters that are internal to npm, and are |
|||
defaults if nothing else is specified. |
|||
|
|||
## Sub-commands |
|||
|
|||
Config supports the following sub-commands: |
|||
|
|||
### set |
|||
|
|||
npm config set key value |
|||
|
|||
Sets the config key to the value. |
|||
|
|||
If value is omitted, then it sets it to "true". |
|||
|
|||
### get |
|||
|
|||
npm config get key |
|||
|
|||
Echo the config value to stdout. |
|||
|
|||
### list |
|||
|
|||
npm config list |
|||
|
|||
Show all the config settings. |
|||
|
|||
### delete |
|||
|
|||
npm config delete key |
|||
|
|||
Deletes the key from all configuration files. |
|||
|
|||
### edit |
|||
|
|||
npm config edit |
|||
|
|||
Opens the config file in an editor. Use the `--global` flag to edit the |
|||
global config. |
|||
|
|||
## Shorthands and Other CLI Niceties |
|||
|
|||
The following shorthands are parsed on the command-line: |
|||
|
|||
* `-v`: `--version` |
|||
* `-h`, `-?`, `--help`, `-H`: `--usage` |
|||
* `-s`, `--silent`: `--loglevel silent` |
|||
* `-q`, `--quiet`: `--loglevel warn` |
|||
* `-d`: `--loglevel info` |
|||
* `-dd`, `--verbose`: `--loglevel verbose` |
|||
* `-ddd`: `--loglevel silly` |
|||
* `-g`: `--global` |
|||
* `-l`: `--long` |
|||
* `-m`: `--message` |
|||
* `-p`, `--porcelain`: `--parseable` |
|||
* `-reg`: `--registry` |
|||
* `-v`: `--version` |
|||
* `-f`: `--force` |
|||
* `-desc`: `--description` |
|||
* `-S`: `--save` |
|||
* `-D`: `--save-dev` |
|||
* `-O`: `--save-optional` |
|||
* `-B`: `--save-bundle` |
|||
* `-y`: `--yes` |
|||
* `-n`: `--yes false` |
|||
* `ll` and `la` commands: `ls --long` |
|||
|
|||
If the specified configuration param resolves unambiguously to a known |
|||
configuration parameter, then it is expanded to that configuration |
|||
parameter. For example: |
|||
|
|||
npm ls --par |
|||
# same as: |
|||
npm ls --parseable |
|||
|
|||
If multiple single-character shorthands are strung together, and the |
|||
resulting combination is unambiguously not some other configuration |
|||
param, then it is expanded to its various component pieces. For |
|||
example: |
|||
|
|||
npm ls -gpld |
|||
# same as: |
|||
npm ls --global --parseable --long --loglevel info |
|||
|
|||
## Per-Package Config Settings |
|||
|
|||
When running scripts (see `npm-scripts(1)`) |
|||
the package.json "config" keys are overwritten in the environment if |
|||
there is a config param of `<name>[@<version>]:<key>`. For example, if |
|||
the package.json has this: |
|||
|
|||
{ "name" : "foo" |
|||
, "config" : { "port" : "8080" } |
|||
, "scripts" : { "start" : "node server.js" } } |
|||
|
|||
and the server.js is this: |
|||
|
|||
http.createServer(...).listen(process.env.npm_package_config_port) |
|||
|
|||
then the user could change the behavior by doing: |
|||
|
|||
npm config set foo:port 80 |
|||
|
|||
## Config Settings |
|||
|
|||
### always-auth |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Force npm to always require authentication when accessing the registry, |
|||
even for `GET` requests. |
|||
|
|||
### bin-links |
|||
|
|||
* Default: `true` |
|||
* Type: Boolean |
|||
|
|||
Tells npm to create symlinks (or `.cmd` shims on Windows) for package |
|||
executables. |
|||
|
|||
Set to false to have it not do this. This can be used to work around |
|||
the fact that some file systems don't support symlinks, even on |
|||
ostensibly Unix systems. |
|||
|
|||
### browser |
|||
|
|||
* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` |
|||
* Type: String |
|||
|
|||
The browser that is called by the `npm docs` command to open websites. |
|||
|
|||
### ca |
|||
|
|||
* Default: The npm CA certificate |
|||
* Type: String or null |
|||
|
|||
The Certificate Authority signing certificate that is trusted for SSL |
|||
connections to the registry. |
|||
|
|||
Set to `null` to only allow "known" registrars, or to a specific CA cert |
|||
to trust only that specific signing authority. |
|||
|
|||
See also the `strict-ssl` config. |
|||
|
|||
### cache |
|||
|
|||
* Default: Windows: `%APPDATA%\npm-cache`, Posix: `~/.npm` |
|||
* Type: path |
|||
|
|||
The location of npm's cache directory. See `npm-cache(1)` |
|||
|
|||
### cache-lock-stale |
|||
|
|||
* Default: 60000 (1 minute) |
|||
* Type: Number |
|||
|
|||
The number of ms before cache folder lockfiles are considered stale. |
|||
|
|||
### cache-lock-retries |
|||
|
|||
* Default: 10 |
|||
* Type: Number |
|||
|
|||
Number of times to retry to acquire a lock on cache folder lockfiles. |
|||
|
|||
### cache-lock-wait |
|||
|
|||
* Default: 10000 (10 seconds) |
|||
* Type: Number |
|||
|
|||
Number of ms to wait for cache lock files to expire. |
|||
|
|||
### cache-max |
|||
|
|||
* Default: Infinity |
|||
* Type: Number |
|||
|
|||
The maximum time (in seconds) to keep items in the registry cache before |
|||
re-checking against the registry. |
|||
|
|||
Note that no purging is done unless the `npm cache clean` command is |
|||
explicitly used, and that only GET requests use the cache. |
|||
|
|||
### cache-min |
|||
|
|||
* Default: 10 |
|||
* Type: Number |
|||
|
|||
The minimum time (in seconds) to keep items in the registry cache before |
|||
re-checking against the registry. |
|||
|
|||
Note that no purging is done unless the `npm cache clean` command is |
|||
explicitly used, and that only GET requests use the cache. |
|||
|
|||
### color |
|||
|
|||
* Default: true on Posix, false on Windows |
|||
* Type: Boolean or `"always"` |
|||
|
|||
If false, never shows colors. If `"always"` then always shows colors. |
|||
If true, then only prints color codes for tty file descriptors. |
|||
|
|||
### coverage |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
A flag to tell test-harness to run with their coverage options enabled, |
|||
if they respond to the `npm_config_coverage` environment variable. |
|||
|
|||
### depth |
|||
|
|||
* Default: Infinity |
|||
* Type: Number |
|||
|
|||
The depth to go when recursing directories for `npm ls` and |
|||
`npm cache ls`. |
|||
|
|||
### description |
|||
|
|||
* Default: true |
|||
* Type: Boolean |
|||
|
|||
Show the description in `npm search` |
|||
|
|||
### dev |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Install `dev-dependencies` along with packages. |
|||
|
|||
Note that `dev-dependencies` are also installed if the `npat` flag is |
|||
set. |
|||
|
|||
### editor |
|||
|
|||
* Default: `EDITOR` environment variable if set, or `"vi"` on Posix, |
|||
or `"notepad"` on Windows. |
|||
* Type: path |
|||
|
|||
The command to run for `npm edit` or `npm config edit`. |
|||
|
|||
### engine-strict |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
If set to true, then npm will stubbornly refuse to install (or even |
|||
consider installing) any package that claims to not be compatible with |
|||
the current Node.js version. |
|||
|
|||
### force |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Makes various commands more forceful. |
|||
|
|||
* lifecycle script failure does not block progress. |
|||
* publishing clobbers previously published versions. |
|||
* skips cache when requesting from the registry. |
|||
* prevents checks against clobbering non-npm files. |
|||
|
|||
### fetch-retries |
|||
|
|||
* Default: 2 |
|||
* Type: Number |
|||
|
|||
The "retries" config for the `retry` module to use when fetching |
|||
packages from the registry. |
|||
|
|||
### fetch-retry-factor |
|||
|
|||
* Default: 10 |
|||
* Type: Number |
|||
|
|||
The "factor" config for the `retry` module to use when fetching |
|||
packages. |
|||
|
|||
### fetch-retry-mintimeout |
|||
|
|||
* Default: 10000 (10 seconds) |
|||
* Type: Number |
|||
|
|||
The "minTimeout" config for the `retry` module to use when fetching |
|||
packages. |
|||
|
|||
### fetch-retry-maxtimeout |
|||
|
|||
* Default: 60000 (1 minute) |
|||
* Type: Number |
|||
|
|||
The "maxTimeout" config for the `retry` module to use when fetching |
|||
packages. |
|||
|
|||
### git |
|||
|
|||
* Default: `"git"` |
|||
* Type: String |
|||
|
|||
The command to use for git commands. If git is installed on the |
|||
computer, but is not in the `PATH`, then set this to the full path to |
|||
the git binary. |
|||
|
|||
### global |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Operates in "global" mode, so that packages are installed into the |
|||
`prefix` folder instead of the current working directory. See |
|||
`npm-folders(1)` for more on the differences in behavior. |
|||
|
|||
* packages are installed into the `{prefix}/lib/node_modules` folder, instead of the |
|||
current working directory. |
|||
* bin files are linked to `{prefix}/bin` |
|||
* man pages are linked to `{prefix}/share/man` |
|||
|
|||
### globalconfig |
|||
|
|||
* Default: {prefix}/etc/npmrc |
|||
* Type: path |
|||
|
|||
The config file to read for global config options. |
|||
|
|||
### globalignorefile |
|||
|
|||
* Default: {prefix}/etc/npmignore |
|||
* Type: path |
|||
|
|||
The config file to read for global ignore patterns to apply to all users |
|||
and all projects. |
|||
|
|||
If not found, but there is a "gitignore" file in the |
|||
same directory, then that will be used instead. |
|||
|
|||
### group |
|||
|
|||
* Default: GID of the current process |
|||
* Type: String or Number |
|||
|
|||
The group to use when running package scripts in global mode as the root |
|||
user. |
|||
|
|||
### https-proxy |
|||
|
|||
* Default: the `HTTPS_PROXY` or `https_proxy` or `HTTP_PROXY` or |
|||
`http_proxy` environment variables. |
|||
* Type: url |
|||
|
|||
A proxy to use for outgoing https requests. |
|||
|
|||
### user-agent |
|||
|
|||
* Default: node/{process.version} {process.platform} {process.arch} |
|||
* Type: String |
|||
|
|||
Sets a User-Agent to the request header |
|||
|
|||
### ignore |
|||
|
|||
* Default: "" |
|||
* Type: string |
|||
|
|||
A white-space separated list of glob patterns of files to always exclude |
|||
from packages when building tarballs. |
|||
|
|||
### init-module |
|||
|
|||
* Default: ~/.npm-init.js |
|||
* Type: path |
|||
|
|||
A module that will be loaded by the `npm init` command. See the |
|||
documentation for the |
|||
[init-package-json](https://github.com/isaacs/init-package-json) module |
|||
for more information, or npm-init(1). |
|||
|
|||
### init.version |
|||
|
|||
* Default: "0.0.0" |
|||
* Type: semver |
|||
|
|||
The value `npm init` should use by default for the package version. |
|||
|
|||
### init.author.name |
|||
|
|||
* Default: "" |
|||
* Type: String |
|||
|
|||
The value `npm init` should use by default for the package author's name. |
|||
|
|||
### init.author.email |
|||
|
|||
* Default: "" |
|||
* Type: String |
|||
|
|||
The value `npm init` should use by default for the package author's email. |
|||
|
|||
### init.author.url |
|||
|
|||
* Default: "" |
|||
* Type: String |
|||
|
|||
The value `npm init` should use by default for the package author's homepage. |
|||
|
|||
### json |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Whether or not to output JSON data, rather than the normal output. |
|||
|
|||
This feature is currently experimental, and the output data structures |
|||
for many commands is either not implemented in JSON yet, or subject to |
|||
change. Only the output from `npm ls --json` is currently valid. |
|||
|
|||
### link |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
If true, then local installs will link if there is a suitable globally |
|||
installed package. |
|||
|
|||
Note that this means that local installs can cause things to be |
|||
installed into the global space at the same time. The link is only done |
|||
if one of the two conditions are met: |
|||
|
|||
* The package is not already installed globally, or |
|||
* the globally installed version is identical to the version that is |
|||
being installed locally. |
|||
|
|||
### loglevel |
|||
|
|||
* Default: "http" |
|||
* Type: String |
|||
* Values: "silent", "win", "error", "warn", "http", "info", "verbose", "silly" |
|||
|
|||
What level of logs to report. On failure, *all* logs are written to |
|||
`npm-debug.log` in the current working directory. |
|||
|
|||
Any logs of a higher level than the setting are shown. |
|||
The default is "http", which shows http, warn, and error output. |
|||
|
|||
### logstream |
|||
|
|||
* Default: process.stderr |
|||
* Type: Stream |
|||
|
|||
This is the stream that is passed to the |
|||
[npmlog](https://github.com/isaacs/npmlog) module at run time. |
|||
|
|||
It cannot be set from the command line, but if you are using npm |
|||
programmatically, you may wish to send logs to somewhere other than |
|||
stderr. |
|||
|
|||
If the `color` config is set to true, then this stream will receive |
|||
colored output if it is a TTY. |
|||
|
|||
### long |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Show extended information in `npm ls` |
|||
|
|||
### message |
|||
|
|||
* Default: "%s" |
|||
* Type: String |
|||
|
|||
Commit message which is used by `npm version` when creating version commit. |
|||
|
|||
Any "%s" in the message will be replaced with the version number. |
|||
|
|||
### node-version |
|||
|
|||
* Default: process.version |
|||
* Type: semver or false |
|||
|
|||
The node version to use when checking package's "engines" hash. |
|||
|
|||
### npat |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Run tests on installation and report results to the |
|||
`npaturl`. |
|||
|
|||
### npaturl |
|||
|
|||
* Default: Not yet implemented |
|||
* Type: url |
|||
|
|||
The url to report npat test results. |
|||
|
|||
### onload-script |
|||
|
|||
* Default: false |
|||
* Type: path |
|||
|
|||
A node module to `require()` when npm loads. Useful for programmatic |
|||
usage. |
|||
|
|||
### optional |
|||
|
|||
* Default: true |
|||
* Type: Boolean |
|||
|
|||
Attempt to install packages in the `optionalDependencies` hash. Note |
|||
that if these packages fail to install, the overall installation |
|||
process is not aborted. |
|||
|
|||
### parseable |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Output parseable results from commands that write to |
|||
standard output. |
|||
|
|||
### prefix |
|||
|
|||
* Default: see npm-folders(1) |
|||
* Type: path |
|||
|
|||
The location to install global items. If set on the command line, then |
|||
it forces non-global commands to run in the specified folder. |
|||
|
|||
### production |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Set to true to run in "production" mode. |
|||
|
|||
1. devDependencies are not installed at the topmost level when running |
|||
local `npm install` without any arguments. |
|||
2. Set the NODE_ENV="production" for lifecycle scripts. |
|||
|
|||
### proprietary-attribs |
|||
|
|||
* Default: true |
|||
* Type: Boolean |
|||
|
|||
Whether or not to include proprietary extended attributes in the |
|||
tarballs created by npm. |
|||
|
|||
Unless you are expecting to unpack package tarballs with something other |
|||
than npm -- particularly a very outdated tar implementation -- leave |
|||
this as true. |
|||
|
|||
### proxy |
|||
|
|||
* Default: `HTTP_PROXY` or `http_proxy` environment variable, or null |
|||
* Type: url |
|||
|
|||
A proxy to use for outgoing http requests. |
|||
|
|||
### rebuild-bundle |
|||
|
|||
* Default: true |
|||
* Type: Boolean |
|||
|
|||
Rebuild bundled dependencies after installation. |
|||
|
|||
### registry |
|||
|
|||
* Default: https://registry.npmjs.org/ |
|||
* Type: url |
|||
|
|||
The base URL of the npm package registry. |
|||
|
|||
### rollback |
|||
|
|||
* Default: true |
|||
* Type: Boolean |
|||
|
|||
Remove failed installs. |
|||
|
|||
### save |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Save installed packages to a package.json file as dependencies. |
|||
|
|||
When used with the `npm rm` command, it removes it from the dependencies |
|||
hash. |
|||
|
|||
Only works if there is already a package.json file present. |
|||
|
|||
### save-bundle |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
If a package would be saved at install time by the use of `--save`, |
|||
`--save-dev`, or `--save-optional`, then also put it in the |
|||
`bundleDependencies` list. |
|||
|
|||
When used with the `npm rm` command, it removes it from the |
|||
bundledDependencies list. |
|||
|
|||
### save-dev |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Save installed packages to a package.json file as devDependencies. |
|||
|
|||
When used with the `npm rm` command, it removes it from the devDependencies |
|||
hash. |
|||
|
|||
Only works if there is already a package.json file present. |
|||
|
|||
### save-optional |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Save installed packages to a package.json file as optionalDependencies. |
|||
|
|||
When used with the `npm rm` command, it removes it from the devDependencies |
|||
hash. |
|||
|
|||
Only works if there is already a package.json file present. |
|||
|
|||
### searchopts |
|||
|
|||
* Default: "" |
|||
* Type: String |
|||
|
|||
Space-separated options that are always passed to search. |
|||
|
|||
### searchexclude |
|||
|
|||
* Default: "" |
|||
* Type: String |
|||
|
|||
Space-separated options that limit the results from search. |
|||
|
|||
### searchsort |
|||
|
|||
* Default: "name" |
|||
* Type: String |
|||
* Values: "name", "-name", "date", "-date", "description", |
|||
"-description", "keywords", "-keywords" |
|||
|
|||
Indication of which field to sort search results by. Prefix with a `-` |
|||
character to indicate reverse sort. |
|||
|
|||
### shell |
|||
|
|||
* Default: SHELL environment variable, or "bash" on Posix, or "cmd" on |
|||
Windows |
|||
* Type: path |
|||
|
|||
The shell to run for the `npm explore` command. |
|||
|
|||
### shrinkwrap |
|||
|
|||
* Default: true |
|||
* Type: Boolean |
|||
|
|||
If set to false, then ignore `npm-shrinkwrap.json` files when |
|||
installing. |
|||
|
|||
### sign-git-tag |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
If set to true, then the `npm version` command will tag the version |
|||
using `-s` to add a signature. |
|||
|
|||
Note that git requires you to have set up GPG keys in your git configs |
|||
for this to work properly. |
|||
|
|||
### strict-ssl |
|||
|
|||
* Default: true |
|||
* Type: Boolean |
|||
|
|||
Whether or not to do SSL key validation when making requests to the |
|||
registry via https. |
|||
|
|||
See also the `ca` config. |
|||
|
|||
### tag |
|||
|
|||
* Default: latest |
|||
* Type: String |
|||
|
|||
If you ask npm to install a package and don't tell it a specific version, then |
|||
it will install the specified tag. |
|||
|
|||
Also the tag that is added to the package@version specified by the `npm |
|||
tag` command, if no explicit tag is given. |
|||
|
|||
### tmp |
|||
|
|||
* Default: TMPDIR environment variable, or "/tmp" |
|||
* Type: path |
|||
|
|||
Where to store temporary files and folders. All temp files are deleted |
|||
on success, but left behind on failure for forensic purposes. |
|||
|
|||
### unicode |
|||
|
|||
* Default: true |
|||
* Type: Boolean |
|||
|
|||
When set to true, npm uses unicode characters in the tree output. When |
|||
false, it uses ascii characters to draw trees. |
|||
|
|||
### unsafe-perm |
|||
|
|||
* Default: false if running as root, true otherwise |
|||
* Type: Boolean |
|||
|
|||
Set to true to suppress the UID/GID switching when running package |
|||
scripts. If set explicitly to false, then installing as a non-root user |
|||
will fail. |
|||
|
|||
### usage |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Set to show short usage output (like the -H output) |
|||
instead of complete help when doing `npm-help(1)`. |
|||
|
|||
### user |
|||
|
|||
* Default: "nobody" |
|||
* Type: String or Number |
|||
|
|||
The UID to set to when running package scripts as root. |
|||
|
|||
### username |
|||
|
|||
* Default: null |
|||
* Type: String |
|||
|
|||
The username on the npm registry. Set with `npm adduser` |
|||
|
|||
### userconfig |
|||
|
|||
* Default: ~/.npmrc |
|||
* Type: path |
|||
|
|||
The location of user-level configuration settings. |
|||
|
|||
### userignorefile |
|||
|
|||
* Default: ~/.npmignore |
|||
* Type: path |
|||
|
|||
The location of a user-level ignore file to apply to all packages. |
|||
|
|||
If not found, but there is a .gitignore file in the same directory, then |
|||
that will be used instead. |
|||
|
|||
### umask |
|||
|
|||
* Default: 022 |
|||
* Type: Octal numeric string |
|||
|
|||
The "umask" value to use when setting the file creation mode on files |
|||
and folders. |
|||
|
|||
Folders and executables are given a mode which is `0777` masked against |
|||
this value. Other files are given a mode which is `0666` masked against |
|||
this value. Thus, the defaults are `0755` and `0644` respectively. |
|||
|
|||
### version |
|||
|
|||
* Default: false |
|||
* Type: boolean |
|||
|
|||
If true, output the npm version and exit successfully. |
|||
|
|||
Only relevant when specified explicitly on the command line. |
|||
|
|||
### versions |
|||
|
|||
* Default: false |
|||
* Type: boolean |
|||
|
|||
If true, output the npm version as well as node's `process.versions` |
|||
hash, and exit successfully. |
|||
|
|||
Only relevant when specified explicitly on the command line. |
|||
|
|||
### viewer |
|||
|
|||
* Default: "man" on Posix, "browser" on Windows |
|||
* Type: path |
|||
|
|||
The program to use to view help content. |
|||
|
|||
Set to `"browser"` to view html help content in the default web browser. |
|||
|
|||
### yes |
|||
|
|||
* Default: null |
|||
* Type: Boolean or null |
|||
|
|||
If set to `null`, then prompt the user for responses in some |
|||
circumstances. |
|||
|
|||
If set to `true`, then answer "yes" to any prompt. If set to `false` |
|||
then answer "no" to any prompt. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-folders(1) |
|||
* npm(1) |
|||
@ -1,26 +0,0 @@ |
|||
npm-deprecate(1) -- Deprecate a version of a package |
|||
==================================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm deprecate <name>[@<version>] <message> |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This command will update the npm registry entry for a package, providing |
|||
a deprecation warning to all who attempt to install it. |
|||
|
|||
It works on version ranges as well as specific versions, so you can do |
|||
something like this: |
|||
|
|||
npm deprecate my-thing@"< 0.2.3" "critical bug fixed in v0.2.3" |
|||
|
|||
Note that you must be the package owner to deprecate something. See the |
|||
`owner` and `adduser` help topics. |
|||
|
|||
To un-deprecate a package, specify an empty string (`""`) for the `message` argument. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-publish(1) |
|||
* npm-registry(1) |
|||
@ -1,207 +0,0 @@ |
|||
npm-developers(1) -- Developer Guide |
|||
==================================== |
|||
|
|||
## DESCRIPTION |
|||
|
|||
So, you've decided to use npm to develop (and maybe publish/deploy) |
|||
your project. |
|||
|
|||
Fantastic! |
|||
|
|||
There are a few things that you need to do above the simple steps |
|||
that your users will do to install your program. |
|||
|
|||
## About These Documents |
|||
|
|||
These are man pages. If you install npm, you should be able to |
|||
then do `man npm-thing` to get the documentation on a particular |
|||
topic, or `npm help thing` to see the same information. |
|||
|
|||
## What is a `package` |
|||
|
|||
A package is: |
|||
|
|||
* a) a folder containing a program described by a package.json file |
|||
* b) a gzipped tarball containing (a) |
|||
* c) a url that resolves to (b) |
|||
* d) a `<name>@<version>` that is published on the registry with (c) |
|||
* e) a `<name>@<tag>` that points to (d) |
|||
* f) a `<name>` that has a "latest" tag satisfying (e) |
|||
* g) a `git` url that, when cloned, results in (a). |
|||
|
|||
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). |
|||
|
|||
Git urls can be of the form: |
|||
|
|||
git://github.com/user/project.git#commit-ish |
|||
git+ssh://user@hostname:project.git#commit-ish |
|||
git+http://user@hostname/project/blah.git#commit-ish |
|||
git+https://user@hostname/project/blah.git#commit-ish |
|||
|
|||
The `commit-ish` can be any tag, sha, or branch which can be supplied as |
|||
an argument to `git checkout`. The default is `master`. |
|||
|
|||
## The package.json File |
|||
|
|||
You need to have a `package.json` file in the root of your project to do |
|||
much of anything with npm. That is basically the whole interface. |
|||
|
|||
See `npm-json(1)` for details about what goes in that file. At the very |
|||
least, you need: |
|||
|
|||
* 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. |
|||
|
|||
It does not necessarily need to match your github repository name. |
|||
|
|||
So, `node-foo` and `bar-js` are bad names. `foo` or `bar` are better. |
|||
|
|||
* version: |
|||
A semver-compatible version. |
|||
|
|||
* 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. |
|||
|
|||
* author: |
|||
Take some credit. |
|||
|
|||
* scripts: |
|||
If you have a special compilation or installation script, then you |
|||
should put it in the `scripts` hash. You should definitely have at |
|||
least a basic smoke-test command as the "scripts.test" field. |
|||
See npm-scripts(1). |
|||
|
|||
* 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. |
|||
|
|||
* 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. |
|||
|
|||
You can use `npm init` in the root of your package in order to get you |
|||
started with a pretty basic package.json file. See `npm-init(1)` for |
|||
more info. |
|||
|
|||
## Keeping files *out* of your package |
|||
|
|||
Use a `.npmignore` file to keep stuff out of your package. If there's |
|||
no `.npmignore` file, but there *is* a `.gitignore` file, then npm will |
|||
ignore the stuff matched by the `.gitignore` file. If you *want* to |
|||
include something that is excluded by your `.gitignore` file, you can |
|||
create an empty `.npmignore` file to override it. |
|||
|
|||
By default, the following paths and files are ignored, so there's no |
|||
need to add them to `.npmignore` explicitly: |
|||
|
|||
* `.*.swp` |
|||
* `._*` |
|||
* `.DS_Store` |
|||
* `.git` |
|||
* `.hg` |
|||
* `.lock-wscript` |
|||
* `.svn` |
|||
* `.wafpickle-*` |
|||
* `CVS` |
|||
* `npm-debug.log` |
|||
|
|||
Additionally, everything in `node_modules` is ignored, except for |
|||
bundled dependencies. npm automatically handles this for you, so don't |
|||
bother adding `node_modules` to `.npmignore`. |
|||
|
|||
The following paths and files are never ignored, so adding them to |
|||
`.npmignore` is pointless: |
|||
|
|||
* `package.json` |
|||
* `README.*` |
|||
|
|||
## Link Packages |
|||
|
|||
`npm link` is designed to install a development package and see the |
|||
changes in real time without having to keep re-installing it. (You do |
|||
need to either re-link or `npm rebuild -g` to update compiled packages, |
|||
of course.) |
|||
|
|||
More info at `npm-link(1)`. |
|||
|
|||
## Before Publishing: Make Sure Your Package Installs and Works |
|||
|
|||
**This is important.** |
|||
|
|||
If you can not install it locally, you'll have |
|||
problems trying to publish it. Or, worse yet, you'll be able to |
|||
publish it, but you'll be publishing a broken or pointless package. |
|||
So don't do that. |
|||
|
|||
In the root of your package, do this: |
|||
|
|||
npm install . -g |
|||
|
|||
That'll show you that it's working. If you'd rather just create a symlink |
|||
package that points to your working directory, then do this: |
|||
|
|||
npm link |
|||
|
|||
Use `npm ls -g` to see if it's there. |
|||
|
|||
To test a local install, go into some other folder, and then do: |
|||
|
|||
cd ../some-other-folder |
|||
npm install ../my-package |
|||
|
|||
to install it locally into the node_modules folder in that other place. |
|||
|
|||
Then go into the node-repl, and try using require("my-thing") to |
|||
bring in your module's main module. |
|||
|
|||
## Create a User Account |
|||
|
|||
Create a user with the adduser command. It works like this: |
|||
|
|||
npm adduser |
|||
|
|||
and then follow the prompts. |
|||
|
|||
This is documented better in npm-adduser(1). |
|||
|
|||
## Publish your package |
|||
|
|||
This part's easy. IN the root of your folder, do this: |
|||
|
|||
npm publish |
|||
|
|||
You can give publish a url to a tarball, or a filename of a tarball, |
|||
or a path to a folder. |
|||
|
|||
Note that pretty much **everything in that folder will be exposed** |
|||
by default. So, if you have secret stuff in there, use a |
|||
`.npmignore` file to list out the globs to ignore, or publish |
|||
from a fresh checkout. |
|||
|
|||
## Brag about it |
|||
|
|||
Send emails, write blogs, blab in IRC. |
|||
|
|||
Tell the world how easy it is to install your program! |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-faq(1) |
|||
* npm(1) |
|||
* npm-init(1) |
|||
* npm-json(1) |
|||
* npm-scripts(1) |
|||
* npm-publish(1) |
|||
* npm-adduser(1) |
|||
* npm-registry(1) |
|||
@ -1,98 +0,0 @@ |
|||
npm-disputes(1) -- Handling Module Name Disputes |
|||
================================================ |
|||
|
|||
## SYNOPSIS |
|||
|
|||
1. Get the author email with `npm owner ls <pkgname>` |
|||
2. Email the author, CC <i@izs.me>. |
|||
3. After a few weeks, if there's no resolution, we'll sort it out. |
|||
|
|||
Don't squat on package names. Publish code or move out of the way. |
|||
|
|||
## DESCRIPTION |
|||
|
|||
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.) |
|||
|
|||
1. Joe writes a JavaScript module `foo`, which is not node-specific. |
|||
Joe doesn't use node at all. Bob wants to use `foo` 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. |
|||
2. Bob writes an npm module `foo`, and publishes it. Perhaps much |
|||
later, Joe finds a bug in `foo`, 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 `foo`, but can't, because the name is |
|||
taken. |
|||
3. Bob writes a 10-line flow-control library, and calls it `foo`, 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 `foo` JavaScript |
|||
toolkit framework. They publish it to npm as `foojs`, but people are |
|||
routinely confused when `npm install foo` is some different thing. |
|||
4. Bob writes a parser for the widely-known `foo` 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 `foo` parser, |
|||
but can't publish, because Bob's `foo` is in the way. |
|||
|
|||
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. |
|||
|
|||
1. `npm owner ls foo`. This will tell Joe the email address of the |
|||
owner (Bob). |
|||
2. Joe emails Bob, explaining the situation **as respectfully as possible**, |
|||
and what he would like to do with the module name. He adds |
|||
isaacs <i@izs.me> to the CC list of the email. Mention in the email |
|||
that Bob can run `npm owner add joe foo` to add Joe as an owner of |
|||
the `foo` package. |
|||
3. After a reasonable amount of time, if Bob has not responded, or if |
|||
Bob and Joe can't come to any sort of resolution, email isaacs |
|||
<i@izs.me> and we'll sort it out. ("Reasonable" is usually about 4 |
|||
weeks, but extra time is allowed around common holidays.) |
|||
|
|||
## REASONING |
|||
|
|||
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. |
|||
|
|||
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. |
|||
|
|||
## EXCEPTIONS |
|||
|
|||
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: |
|||
|
|||
1. Malware (that is, a package designed to exploit or harm the machine on |
|||
which it is installed). |
|||
2. Violations of copyright or licenses (for example, cloning an |
|||
MIT-licensed program, and then removing or changing the copyright and |
|||
license statement). |
|||
3. Illegal content. |
|||
4. "Squatting" on a package name that you *plan* 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. |
|||
5. Putting empty packages in the registry. Packages must have SOME |
|||
functionality. It can be silly, but it can't be *nothing*. (See |
|||
also: squatting.) |
|||
6. Doing weird things with the registry, like using it as your own |
|||
personal application database or otherwise putting non-packagey |
|||
things into it. |
|||
|
|||
If you see bad behavior like this, please report it right away. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-registry(1) |
|||
* npm-owner(1) |
|||
@ -1,38 +0,0 @@ |
|||
npm-docs(1) -- Docs for a package in a web browser maybe |
|||
======================================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm docs <pkgname> |
|||
npm home <pkgname> |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This command tries to guess at the likely location of a package's |
|||
documentation URL, and then tries to open it using the `--browser` |
|||
config param. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### browser |
|||
|
|||
* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` |
|||
* Type: String |
|||
|
|||
The browser that is called by the `npm docs` command to open websites. |
|||
|
|||
### registry |
|||
|
|||
* Default: https://registry.npmjs.org/ |
|||
* Type: url |
|||
|
|||
The base URL of the npm package registry. |
|||
|
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-view(1) |
|||
* npm-publish(1) |
|||
* npm-registry(1) |
|||
* npm-config(1) |
|||
* npm-json(1) |
|||
@ -1,35 +0,0 @@ |
|||
npm-edit(1) -- Edit an installed package |
|||
======================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm edit <name>[@<version>] |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Opens the package folder in the default editor (or whatever you've |
|||
configured as the npm `editor` config -- see `npm-config(1)`.) |
|||
|
|||
After it has been edited, the package is rebuilt so as to pick up any |
|||
changes in compiled packages. |
|||
|
|||
For instance, you can do `npm install connect` to install connect |
|||
into your package, and then `npm edit connect` to make a few |
|||
changes to your locally installed copy. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### editor |
|||
|
|||
* Default: `EDITOR` environment variable if set, or `"vi"` on Posix, |
|||
or `"notepad"` on Windows. |
|||
* Type: path |
|||
|
|||
The command to run for `npm edit` or `npm config edit`. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-folders(1) |
|||
* npm-explore(1) |
|||
* npm-install(1) |
|||
* npm-config(1) |
|||
@ -1,40 +0,0 @@ |
|||
npm-explore(1) -- Browse an installed package |
|||
============================================= |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm explore <name>[@<version>] [ -- <cmd>] |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Spawn a subshell in the directory of the installed package specified. |
|||
|
|||
If a command is specified, then it is run in the subshell, which then |
|||
immediately terminates. |
|||
|
|||
This is particularly handy in the case of git submodules in the |
|||
`node_modules` folder: |
|||
|
|||
npm explore some-dependency -- git pull origin master |
|||
|
|||
Note that the package is *not* automatically rebuilt afterwards, so be |
|||
sure to use `npm rebuild <pkg>` if you make any changes. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### shell |
|||
|
|||
* Default: SHELL environment variable, or "bash" on Posix, or "cmd" on |
|||
Windows |
|||
* Type: path |
|||
|
|||
The shell to run for the `npm explore` command. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-submodule(1) |
|||
* npm-folders(1) |
|||
* npm-edit(1) |
|||
* npm-rebuild(1) |
|||
* npm-build(1) |
|||
* npm-install(1) |
|||
@ -1,313 +0,0 @@ |
|||
npm-faq(1) -- Frequently Asked Questions |
|||
======================================== |
|||
|
|||
## Where can I find these docs in HTML? |
|||
|
|||
<https://npmjs.org/doc/>, or run: |
|||
|
|||
npm config set viewer browser |
|||
|
|||
to open these documents in your default web browser rather than `man`. |
|||
|
|||
## It didn't work. |
|||
|
|||
That's not really a question. |
|||
|
|||
## Why didn't it work? |
|||
|
|||
I don't know yet. |
|||
|
|||
Read the error output, and if you can't figure out what it means, |
|||
do what it says and post a bug with all the information it asks for. |
|||
|
|||
## Where does npm put stuff? |
|||
|
|||
See `npm-folders(1)` |
|||
|
|||
tl;dr: |
|||
|
|||
* Use the `npm root` command to see where modules go, and the `npm bin` |
|||
command to see where executables go |
|||
* Global installs are different from local installs. If you install |
|||
something with the `-g` flag, then its executables go in `npm bin -g` |
|||
and its modules go in `npm root -g`. |
|||
|
|||
## How do I install something on my computer in a central location? |
|||
|
|||
Install it globally by tacking `-g` or `--global` to the command. (This |
|||
is especially important for command line utilities that need to add |
|||
their bins to the global system `PATH`.) |
|||
|
|||
## I installed something globally, but I can't `require()` it |
|||
|
|||
Install it locally. |
|||
|
|||
The global install location is a place for command-line utilities |
|||
to put their bins in the system `PATH`. It's not for use with `require()`. |
|||
|
|||
If you `require()` 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. |
|||
|
|||
## Why can't npm just put everything in one place, like other package managers? |
|||
|
|||
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. |
|||
|
|||
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 `npm-folders(1)` for |
|||
more details. |
|||
|
|||
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 `npm link` command. |
|||
That's what it's for. Install it globally, then link it into each |
|||
program that uses it. |
|||
|
|||
## Whatever, I really want the old style 'everything global' style. |
|||
|
|||
Write your own package manager, then. It's not that hard. |
|||
|
|||
npm will not help you do something that is known to be a bad idea. |
|||
|
|||
## `"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? |
|||
|
|||
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? |
|||
|
|||
At the time of this writing, the string `'node_modules'` appears 151 |
|||
times in 53 separate files in npm and node core (excluding tests and |
|||
documentation). |
|||
|
|||
Some of these references are in node's built-in module loader. Since |
|||
npm is not involved **at all** 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. |
|||
|
|||
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 `node_modules` folder as a |
|||
parameter. Complexity hurdle #2. |
|||
|
|||
Furthermore, npm has the ability to "bundle" dependencies by adding |
|||
the dep names to the `"bundledDependencies"` list in package.json, |
|||
which causes the folder to be included in the package tarball. What |
|||
if the author of a module bundles its dependencies, and they use a |
|||
different spelling for `node_modules`? 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. |
|||
|
|||
Furthermore, what happens when you *change* this name? Fine, it's |
|||
easy enough the first time, just rename the `node_modules` folders to |
|||
`./blergyblerp/` or whatever name you choose. But what about when you |
|||
change it again? npm doesn't currently track any state about past |
|||
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. |
|||
|
|||
Never going to happen. The folder is named `node_modules`. It is |
|||
written indelibly in the Node Way, handed down from the ancient times |
|||
of Node 0.3. |
|||
|
|||
## Should I check my `node_modules` folder into git? |
|||
|
|||
Mikeal Rogers answered this question very well: |
|||
|
|||
<http://www.mikealrogers.com/posts/nodemodules-in-git.html> |
|||
|
|||
tl;dr |
|||
|
|||
* Check `node_modules` into git for things you **deploy**, such as |
|||
websites and apps. |
|||
* Do not check `node_modules` into git for libraries and modules |
|||
intended to be reused. |
|||
* Use npm to manage dependencies in your dev environment, but not in |
|||
your deployment scripts. |
|||
|
|||
## Is it 'npm' or 'NPM' or 'Npm'? |
|||
|
|||
npm should never be capitalized unless it is being displayed in a |
|||
location that is customarily all-caps (such as the title of man pages.) |
|||
|
|||
## If 'npm' is an acronym, why is it never capitalized? |
|||
|
|||
Contrary to the belief of many, "npm" is not in fact an abbreviation for |
|||
"Node Package Manager". It is a recursive bacronymic abbreviation for |
|||
"npm is not an acronym". (If it was "ninaa", then it would be an |
|||
acronym, and thus incorrectly named.) |
|||
|
|||
"NPM", however, *is* an acronym (more precisely, a capitonym) for the |
|||
National Association of Pastoral Musicians. You can learn more |
|||
about them at <http://npm.org/>. |
|||
|
|||
In software, "NPM" is a Non-Parametric Mapping utility written by |
|||
Chris Rorden. You can analyze pictures of brains with it. Learn more |
|||
about the (capitalized) NPM program at <http://www.cabiatl.com/mricro/npm/>. |
|||
|
|||
The first seed that eventually grew into this flower was a bash utility |
|||
named "pm", which was a shortened descendent of "pkgmakeinst", a |
|||
bash function that was used to install various different things on different |
|||
platforms, most often using Yahoo's `yinst`. If `npm` was ever an |
|||
acronym for anything, it was `node pm` or maybe `new pm`. |
|||
|
|||
So, in all seriousness, the "npm" project is named after its command-line |
|||
utility, which was organically selected to be easily typed by a right-handed |
|||
programmer using a US QWERTY keyboard layout, ending with the |
|||
right-ring-finger in a postition to type the `-` key for flags and |
|||
other command-line arguments. That command-line utility is always |
|||
lower-case, though it starts most sentences it is a part of. |
|||
|
|||
## How do I list installed packages? |
|||
|
|||
`npm ls` |
|||
|
|||
## How do I search for packages? |
|||
|
|||
`npm search` |
|||
|
|||
Arguments are greps. `npm search jsdom` shows jsdom packages. |
|||
|
|||
## How do I update npm? |
|||
|
|||
npm update npm -g |
|||
|
|||
You can also update all outdated local packages by doing `npm update` without |
|||
any arguments, or global packages by doing `npm update -g`. |
|||
|
|||
Occasionally, the version of npm will progress such that the current |
|||
version cannot be properly installed with the version that you have |
|||
installed already. (Consider, if there is ever a bug in the `update` |
|||
command.) |
|||
|
|||
In those cases, you can do this: |
|||
|
|||
curl https://npmjs.org/install.sh | sh |
|||
|
|||
## What is a `package`? |
|||
|
|||
A package is: |
|||
|
|||
* a) a folder containing a program described by a package.json file |
|||
* b) a gzipped tarball containing (a) |
|||
* c) a url that resolves to (b) |
|||
* d) a `<name>@<version>` that is published on the registry with (c) |
|||
* e) a `<name>@<tag>` that points to (d) |
|||
* f) a `<name>` that has a "latest" tag satisfying (e) |
|||
* g) a `git` url that, when cloned, results in (a). |
|||
|
|||
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). |
|||
|
|||
Git urls can be of the form: |
|||
|
|||
git://github.com/user/project.git#commit-ish |
|||
git+ssh://user@hostname:project.git#commit-ish |
|||
git+http://user@hostname/project/blah.git#commit-ish |
|||
git+https://user@hostname/project/blah.git#commit-ish |
|||
|
|||
The `commit-ish` can be any tag, sha, or branch which can be supplied as |
|||
an argument to `git checkout`. The default is `master`. |
|||
|
|||
## How do I install node with npm? |
|||
|
|||
You don't. Try one of these node version managers: |
|||
|
|||
Unix: |
|||
|
|||
* <http://github.com/isaacs/nave> |
|||
* <http://github.com/visionmedia/n> |
|||
* <http://github.com/creationix/nvm> |
|||
|
|||
Windows: |
|||
|
|||
* <http://github.com/marcelklehr/nodist> |
|||
* <https://github.com/hakobera/nvmw> |
|||
|
|||
## How can I use npm for development? |
|||
|
|||
See `npm-developers(1)` and `npm-json(1)`. |
|||
|
|||
You'll most likely want to `npm link` your development folder. That's |
|||
awesomely handy. |
|||
|
|||
To set up your own private registry, check out `npm-registry(1)`. |
|||
|
|||
## Can I list a url as a dependency? |
|||
|
|||
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.) |
|||
|
|||
## How do I symlink to a dev folder so I don't have to keep re-installing? |
|||
|
|||
See `npm-link(1)` |
|||
|
|||
## The package registry website. What is that exactly? |
|||
|
|||
See `npm-registry(1)`. |
|||
|
|||
## What's up with the insecure channel warnings? |
|||
|
|||
Until node 0.4.10, there were problems sending big files over HTTPS. That |
|||
means that publishes go over HTTP by default in those versions of node. |
|||
|
|||
## I forgot my password, and can't publish. How do I reset it? |
|||
|
|||
Go to <https://npmjs.org/forgot>. |
|||
|
|||
## I get ECONNREFUSED a lot. What's up? |
|||
|
|||
Either the registry is down, or node's DNS isn't able to reach out. |
|||
|
|||
To check if the registry is down, open up <http://registry.npmjs.org/> |
|||
in a web browser. This will also tell you if you are just unable to |
|||
access the internet for some reason. |
|||
|
|||
If the registry IS down, let me know by emailing or posting an issue. |
|||
We'll have someone kick it or something. |
|||
|
|||
## Why no namespaces? |
|||
|
|||
Please see this discussion: <https://github.com/isaacs/npm/issues/798> |
|||
|
|||
tl;dr - It doesn't actually make things better, and can make them worse. |
|||
|
|||
If you want to namespace your own packages, you may: simply use the |
|||
`-` character to separate the names. npm is a mostly anarchic system. |
|||
There is not sufficient need to impose namespace rules on everyone. |
|||
|
|||
## Who does npm? |
|||
|
|||
`npm view npm author` |
|||
|
|||
`npm view npm contributors` |
|||
|
|||
## I have a question or request not addressed here. Where should I put it? |
|||
|
|||
Discuss it on the mailing list, or post an issue. |
|||
|
|||
* <npm-@googlegroups.com> |
|||
* <https://github.com/isaacs/npm/issues> |
|||
|
|||
## Why does npm hate me? |
|||
|
|||
npm is not capable of hatred. It loves everyone, especially you. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm(1) |
|||
* npm-developers(1) |
|||
* npm-json(1) |
|||
* npm-config(1) |
|||
* npm-folders(1) |
|||
@ -1,209 +0,0 @@ |
|||
npm-folders(1) -- Folder Structures Used by npm |
|||
=============================================== |
|||
|
|||
## DESCRIPTION |
|||
|
|||
npm puts various things on your computer. That's its job. |
|||
|
|||
This document will tell you what it puts where. |
|||
|
|||
### tl;dr |
|||
|
|||
* Local install (default): puts stuff in `./node_modules` of the current |
|||
package root. |
|||
* Global install (with `-g`): puts stuff in /usr/local or wherever node |
|||
is installed. |
|||
* Install it **locally** if you're going to `require()` it. |
|||
* Install it **globally** if you're going to run it on the command line. |
|||
* If you need both, then install it in both places, or use `npm link`. |
|||
|
|||
### prefix Configuration |
|||
|
|||
The `prefix` config defaults to the location where node is installed. |
|||
On most systems, this is `/usr/local`, and most of the time is the same |
|||
as node's `process.installPrefix`. |
|||
|
|||
On windows, this is the exact location of the node.exe binary. On Unix |
|||
systems, it's one level up, since node is typically installed at |
|||
`{prefix}/bin/node` rather than `{prefix}/node.exe`. |
|||
|
|||
When the `global` flag is set, npm installs things into this prefix. |
|||
When it is not set, it uses the root of the current package, or the |
|||
current working directory if not in a package already. |
|||
|
|||
### Node Modules |
|||
|
|||
Packages are dropped into the `node_modules` folder under the `prefix`. |
|||
When installing locally, this means that you can |
|||
`require("packagename")` to load its main module, or |
|||
`require("packagename/lib/path/to/sub/module")` to load other modules. |
|||
|
|||
Global installs on Unix systems go to `{prefix}/lib/node_modules`. |
|||
Global installs on Windows go to `{prefix}/node_modules` (that is, no |
|||
`lib` folder.) |
|||
|
|||
If you wish to `require()` a package, then install it locally. |
|||
|
|||
### Executables |
|||
|
|||
When in global mode, executables are linked into `{prefix}/bin` on Unix, |
|||
or directly into `{prefix}` on Windows. |
|||
|
|||
When in local mode, executables are linked into |
|||
`./node_modules/.bin` so that they can be made available to scripts run |
|||
through npm. (For example, so that a test runner will be in the path |
|||
when you run `npm test`.) |
|||
|
|||
### Man Pages |
|||
|
|||
When in global mode, man pages are linked into `{prefix}/share/man`. |
|||
|
|||
When in local mode, man pages are not installed. |
|||
|
|||
Man pages are not installed on Windows systems. |
|||
|
|||
### Cache |
|||
|
|||
See `npm-cache(1)`. Cache files are stored in `~/.npm` on Posix, or |
|||
`~/npm-cache` on Windows. |
|||
|
|||
This is controlled by the `cache` configuration param. |
|||
|
|||
### Temp Files |
|||
|
|||
Temporary files are stored by default in the folder specified by the |
|||
`tmp` config, which defaults to the TMPDIR, TMP, or TEMP environment |
|||
variables, or `/tmp` on Unix and `c:\windows\temp` on Windows. |
|||
|
|||
Temp files are given a unique folder under this root for each run of the |
|||
program, and are deleted upon successful exit. |
|||
|
|||
## More Information |
|||
|
|||
When installing locally, npm first tries to find an appropriate |
|||
`prefix` folder. This is so that `npm install foo@1.2.3` will install |
|||
to the sensible root of your package, even if you happen to have `cd`ed |
|||
into some other folder. |
|||
|
|||
Starting at the $PWD, npm will walk up the folder tree checking for a |
|||
folder that contains either a `package.json` file, or a `node_modules` |
|||
folder. If such a thing is found, then that is treated as the effective |
|||
"current directory" for the purpose of running npm commands. (This |
|||
behavior is inspired by and similar to git's .git-folder seeking |
|||
logic when running git commands in a working dir.) |
|||
|
|||
If no package root is found, then the current folder is used. |
|||
|
|||
When you run `npm install foo@1.2.3`, then the package is loaded into |
|||
the cache, and then unpacked into `./node_modules/foo`. Then, any of |
|||
foo's dependencies are similarly unpacked into |
|||
`./node_modules/foo/node_modules/...`. |
|||
|
|||
Any bin files are symlinked to `./node_modules/.bin/`, so that they may |
|||
be found by npm scripts when necessary. |
|||
|
|||
### Global Installation |
|||
|
|||
If the `global` configuration is set to true, then npm will |
|||
install packages "globally". |
|||
|
|||
For global installation, packages are installed roughly the same way, |
|||
but using the folders described above. |
|||
|
|||
### Cycles, Conflicts, and Folder Parsimony |
|||
|
|||
Cycles are handled using the property of node's module system that it |
|||
walks up the directories looking for `node_modules` folders. So, at every |
|||
stage, if a package is already installed in an ancestor `node_modules` |
|||
folder, then it is not installed at the current location. |
|||
|
|||
Consider the case above, where `foo -> bar -> baz`. Imagine if, in |
|||
addition to that, baz depended on bar, so you'd have: |
|||
`foo -> bar -> baz -> bar -> baz ...`. However, since the folder |
|||
structure is: `foo/node_modules/bar/node_modules/baz`, there's no need to |
|||
put another copy of bar into `.../baz/node_modules`, since when it calls |
|||
require("bar"), it will get the copy that is installed in |
|||
`foo/node_modules/bar`. |
|||
|
|||
This shortcut is only used if the exact same |
|||
version would be installed in multiple nested `node_modules` folders. It |
|||
is still possible to have `a/node_modules/b/node_modules/a` if the two |
|||
"a" packages are different versions. However, without repeating the |
|||
exact same package multiple times, an infinite regress will always be |
|||
prevented. |
|||
|
|||
Another optimization can be made by installing dependencies at the |
|||
highest level possible, below the localized "target" folder. |
|||
|
|||
#### Example |
|||
|
|||
Consider this dependency graph: |
|||
|
|||
foo |
|||
+-- blerg@1.2.5 |
|||
+-- bar@1.2.3 |
|||
| +-- blerg@1.x (latest=1.3.7) |
|||
| +-- baz@2.x |
|||
| | `-- quux@3.x |
|||
| | `-- bar@1.2.3 (cycle) |
|||
| `-- asdf@* |
|||
`-- baz@1.2.3 |
|||
`-- quux@3.x |
|||
`-- bar |
|||
|
|||
In this case, we might expect a folder structure like this: |
|||
|
|||
foo |
|||
+-- node_modules |
|||
+-- blerg (1.2.5) <---[A] |
|||
+-- bar (1.2.3) <---[B] |
|||
| `-- node_modules |
|||
| +-- baz (2.0.2) <---[C] |
|||
| | `-- node_modules |
|||
| | `-- quux (3.2.0) |
|||
| `-- asdf (2.3.4) |
|||
`-- baz (1.2.3) <---[D] |
|||
`-- node_modules |
|||
`-- quux (3.2.0) <---[E] |
|||
|
|||
Since foo depends directly on `bar@1.2.3` and `baz@1.2.3`, those are |
|||
installed in foo's `node_modules` folder. |
|||
|
|||
Even though the latest copy of blerg is 1.3.7, foo has a specific |
|||
dependency on version 1.2.5. So, that gets installed at [A]. Since the |
|||
parent installation of blerg satisfies bar's dependency on `blerg@1.x`, |
|||
it does not install another copy under [B]. |
|||
|
|||
Bar [B] also has dependencies on baz and asdf, so those are installed in |
|||
bar's `node_modules` folder. Because it depends on `baz@2.x`, it cannot |
|||
re-use the `baz@1.2.3` installed in the parent `node_modules` folder [D], |
|||
and must install its own copy [C]. |
|||
|
|||
Underneath bar, the `baz -> quux -> bar` dependency creates a cycle. |
|||
However, because bar is already in quux's ancestry [B], it does not |
|||
unpack another copy of bar into that folder. |
|||
|
|||
Underneath `foo -> baz` [D], quux's [E] folder tree is empty, because its |
|||
dependency on bar is satisfied by the parent folder copy installed at [B]. |
|||
|
|||
For a graphical breakdown of what is installed where, use `npm ls`. |
|||
|
|||
### Publishing |
|||
|
|||
Upon publishing, npm will look in the `node_modules` folder. If any of |
|||
the items there are not in the `bundledDependencies` array, then they will |
|||
not be included in the package tarball. |
|||
|
|||
This allows a package maintainer to install all of their dependencies |
|||
(and dev dependencies) locally, but only re-publish those items that |
|||
cannot be found elsewhere. See `npm-json(1)` for more information. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-faq(1) |
|||
* npm-json(1) |
|||
* npm-install(1) |
|||
* npm-pack(1) |
|||
* npm-cache(1) |
|||
* npm-config(1) |
|||
* npm-publish(1) |
|||
@ -1,209 +0,0 @@ |
|||
npm-folders(1) -- Folder Structures Used by npm |
|||
=============================================== |
|||
|
|||
## DESCRIPTION |
|||
|
|||
npm puts various things on your computer. That's its job. |
|||
|
|||
This document will tell you what it puts where. |
|||
|
|||
### tl;dr |
|||
|
|||
* Local install (default): puts stuff in `./node_modules` of the current |
|||
package root. |
|||
* Global install (with `-g`): puts stuff in /usr/local or wherever node |
|||
is installed. |
|||
* Install it **locally** if you're going to `require()` it. |
|||
* Install it **globally** if you're going to run it on the command line. |
|||
* If you need both, then install it in both places, or use `npm link`. |
|||
|
|||
### prefix Configuration |
|||
|
|||
The `prefix` config defaults to the location where node is installed. |
|||
On most systems, this is `/usr/local`, and most of the time is the same |
|||
as node's `process.installPrefix`. |
|||
|
|||
On windows, this is the exact location of the node.exe binary. On Unix |
|||
systems, it's one level up, since node is typically installed at |
|||
`{prefix}/bin/node` rather than `{prefix}/node.exe`. |
|||
|
|||
When the `global` flag is set, npm installs things into this prefix. |
|||
When it is not set, it uses the root of the current package, or the |
|||
current working directory if not in a package already. |
|||
|
|||
### Node Modules |
|||
|
|||
Packages are dropped into the `node_modules` folder under the `prefix`. |
|||
When installing locally, this means that you can |
|||
`require("packagename")` to load its main module, or |
|||
`require("packagename/lib/path/to/sub/module")` to load other modules. |
|||
|
|||
Global installs on Unix systems go to `{prefix}/lib/node_modules`. |
|||
Global installs on Windows go to `{prefix}/node_modules` (that is, no |
|||
`lib` folder.) |
|||
|
|||
If you wish to `require()` a package, then install it locally. |
|||
|
|||
### Executables |
|||
|
|||
When in global mode, executables are linked into `{prefix}/bin` on Unix, |
|||
or directly into `{prefix}` on Windows. |
|||
|
|||
When in local mode, executables are linked into |
|||
`./node_modules/.bin` so that they can be made available to scripts run |
|||
through npm. (For example, so that a test runner will be in the path |
|||
when you run `npm test`.) |
|||
|
|||
### Man Pages |
|||
|
|||
When in global mode, man pages are linked into `{prefix}/share/man`. |
|||
|
|||
When in local mode, man pages are not installed. |
|||
|
|||
Man pages are not installed on Windows systems. |
|||
|
|||
### Cache |
|||
|
|||
See `npm-cache(1)`. Cache files are stored in `~/.npm` on Posix, or |
|||
`~/npm-cache` on Windows. |
|||
|
|||
This is controlled by the `cache` configuration param. |
|||
|
|||
### Temp Files |
|||
|
|||
Temporary files are stored by default in the folder specified by the |
|||
`tmp` config, which defaults to the TMPDIR, TMP, or TEMP environment |
|||
variables, or `/tmp` on Unix and `c:\windows\temp` on Windows. |
|||
|
|||
Temp files are given a unique folder under this root for each run of the |
|||
program, and are deleted upon successful exit. |
|||
|
|||
## More Information |
|||
|
|||
When installing locally, npm first tries to find an appropriate |
|||
`prefix` folder. This is so that `npm install foo@1.2.3` will install |
|||
to the sensible root of your package, even if you happen to have `cd`ed |
|||
into some other folder. |
|||
|
|||
Starting at the $PWD, npm will walk up the folder tree checking for a |
|||
folder that contains either a `package.json` file, or a `node_modules` |
|||
folder. If such a thing is found, then that is treated as the effective |
|||
"current directory" for the purpose of running npm commands. (This |
|||
behavior is inspired by and similar to git's .git-folder seeking |
|||
logic when running git commands in a working dir.) |
|||
|
|||
If no package root is found, then the current folder is used. |
|||
|
|||
When you run `npm install foo@1.2.3`, then the package is loaded into |
|||
the cache, and then unpacked into `./node_modules/foo`. Then, any of |
|||
foo's dependencies are similarly unpacked into |
|||
`./node_modules/foo/node_modules/...`. |
|||
|
|||
Any bin files are symlinked to `./node_modules/.bin/`, so that they may |
|||
be found by npm scripts when necessary. |
|||
|
|||
### Global Installation |
|||
|
|||
If the `global` configuration is set to true, then npm will |
|||
install packages "globally". |
|||
|
|||
For global installation, packages are installed roughly the same way, |
|||
but using the folders described above. |
|||
|
|||
### Cycles, Conflicts, and Folder Parsimony |
|||
|
|||
Cycles are handled using the property of node's module system that it |
|||
walks up the directories looking for `node_modules` folders. So, at every |
|||
stage, if a package is already installed in an ancestor `node_modules` |
|||
folder, then it is not installed at the current location. |
|||
|
|||
Consider the case above, where `foo -> bar -> baz`. Imagine if, in |
|||
addition to that, baz depended on bar, so you'd have: |
|||
`foo -> bar -> baz -> bar -> baz ...`. However, since the folder |
|||
structure is: `foo/node_modules/bar/node_modules/baz`, there's no need to |
|||
put another copy of bar into `.../baz/node_modules`, since when it calls |
|||
require("bar"), it will get the copy that is installed in |
|||
`foo/node_modules/bar`. |
|||
|
|||
This shortcut is only used if the exact same |
|||
version would be installed in multiple nested `node_modules` folders. It |
|||
is still possible to have `a/node_modules/b/node_modules/a` if the two |
|||
"a" packages are different versions. However, without repeating the |
|||
exact same package multiple times, an infinite regress will always be |
|||
prevented. |
|||
|
|||
Another optimization can be made by installing dependencies at the |
|||
highest level possible, below the localized "target" folder. |
|||
|
|||
#### Example |
|||
|
|||
Consider this dependency graph: |
|||
|
|||
foo |
|||
+-- blerg@1.2.5 |
|||
+-- bar@1.2.3 |
|||
| +-- blerg@1.x (latest=1.3.7) |
|||
| +-- baz@2.x |
|||
| | `-- quux@3.x |
|||
| | `-- bar@1.2.3 (cycle) |
|||
| `-- asdf@* |
|||
`-- baz@1.2.3 |
|||
`-- quux@3.x |
|||
`-- bar |
|||
|
|||
In this case, we might expect a folder structure like this: |
|||
|
|||
foo |
|||
+-- node_modules |
|||
+-- blerg (1.2.5) <---[A] |
|||
+-- bar (1.2.3) <---[B] |
|||
| +-- node_modules |
|||
| | `-- baz (2.0.2) <---[C] |
|||
| | `-- node_modules |
|||
| | `-- quux (3.2.0) |
|||
| `-- asdf (2.3.4) |
|||
`-- baz (1.2.3) <---[D] |
|||
`-- node_modules |
|||
`-- quux (3.2.0) <---[E] |
|||
|
|||
Since foo depends directly on bar@1.2.3 and baz@1.2.3, those are |
|||
installed in foo's `node_modules` folder. |
|||
|
|||
Even though the latest copy of blerg is 1.3.7, foo has a specific |
|||
dependency on version 1.2.5. So, that gets installed at [A]. Since the |
|||
parent installation of blerg satisfie's bar's dependency on blerg@1.x, |
|||
it does not install another copy under [B]. |
|||
|
|||
Bar [B] also has dependencies on baz and asdf, so those are installed in |
|||
bar's `node_modules` folder. Because it depends on `baz@2.x`, it cannot |
|||
re-use the `baz@1.2.3` installed in the parent `node_modules` folder [D], |
|||
and must install its own copy [C]. |
|||
|
|||
Underneath bar, the `baz->quux->bar` dependency creates a cycle. |
|||
However, because `bar` is already in `quux`'s ancestry [B], it does not |
|||
unpack another copy of bar into that folder. |
|||
|
|||
Underneath `foo->baz` [D], quux's [E] folder tree is empty, because its |
|||
dependency on bar is satisfied by the parent folder copy installed at [B]. |
|||
|
|||
For a graphical breakdown of what is installed where, use `npm ls`. |
|||
|
|||
### Publishing |
|||
|
|||
Upon publishing, npm will look in the `node_modules` folder. If any of |
|||
the items there are not in the `bundledDependencies` array, then they will |
|||
not be included in the package tarball. |
|||
|
|||
This allows a package maintainer to install all of their dependencies |
|||
(and dev dependencies) locally, but only re-publish those items that |
|||
cannot be found elsewhere. See `npm-json(1)` for more information. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-faq(1) |
|||
* npm-json(1) |
|||
* npm-install(1) |
|||
* npm-pack(1) |
|||
* npm-cache(1) |
|||
* npm-config(1) |
|||
* npm-publish(1) |
|||
@ -1,35 +0,0 @@ |
|||
npm-help-search(1) -- Search npm help documentation |
|||
=================================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm help-search some search terms |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This command will search the npm markdown documentation files for the |
|||
terms provided, and then list the results, sorted by relevance. |
|||
|
|||
If only one result is found, then it will show that help topic. |
|||
|
|||
If the argument to `npm help` is not a known help topic, then it will |
|||
call `help-search`. It is rarely if ever necessary to call this |
|||
command directly. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### long |
|||
|
|||
* Type: Boolean |
|||
* Default false |
|||
|
|||
If true, the "long" flag will cause help-search to output context around |
|||
where the terms were found in the documentation. |
|||
|
|||
If false, then help-search will just list out the help topics found. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm(1) |
|||
* npm-faq(1) |
|||
* npm-help(1) |
|||
@ -1,38 +0,0 @@ |
|||
npm-help(1) -- Get help on npm |
|||
============================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm help <topic> |
|||
npm help some search terms |
|||
|
|||
## DESCRIPTION |
|||
|
|||
If supplied a topic, then show the appropriate documentation page. |
|||
|
|||
If the topic does not exist, or if multiple terms are provided, then run |
|||
the `help-search` command to find a match. Note that, if `help-search` |
|||
finds a single subject, then it will run `help` on that topic, so unique |
|||
matches are equivalent to specifying a topic name. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### viewer |
|||
|
|||
* Default: "man" on Posix, "browser" on Windows |
|||
* Type: path |
|||
|
|||
The program to use to view help content. |
|||
|
|||
Set to `"browser"` to view html help content in the default web browser. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm(1) |
|||
* README |
|||
* npm-faq(1) |
|||
* npm-folders(1) |
|||
* npm-config(1) |
|||
* npm-json(1) |
|||
* npm-help-search(1) |
|||
* npm-index(1) |
|||
@ -1,393 +0,0 @@ |
|||
npm-index(1) -- Index of all npm documentation |
|||
============================================== |
|||
|
|||
## npm-README(1) |
|||
|
|||
node package manager |
|||
|
|||
# Command Line Documentation |
|||
## npm-adduser(1) |
|||
|
|||
Add a registry user account |
|||
|
|||
## npm-bin(1) |
|||
|
|||
Display npm bin folder |
|||
|
|||
## npm-bugs(1) |
|||
|
|||
Bugs for a package in a web browser maybe |
|||
|
|||
## npm-build(1) |
|||
|
|||
Build a package |
|||
|
|||
## npm-bundle(1) |
|||
|
|||
REMOVED |
|||
|
|||
## npm-cache(1) |
|||
|
|||
Manipulates packages cache |
|||
|
|||
## npm-changelog(1) |
|||
|
|||
Changes |
|||
|
|||
## npm-coding-style(1) |
|||
|
|||
npm's "funny" coding style |
|||
|
|||
## npm-completion(1) |
|||
|
|||
Tab Completion for npm |
|||
|
|||
## npm-config(1) |
|||
|
|||
Manage the npm configuration file |
|||
|
|||
## npm-dedupe(1) |
|||
|
|||
Reduce duplication |
|||
|
|||
## npm-deprecate(1) |
|||
|
|||
Deprecate a version of a package |
|||
|
|||
## npm-developers(1) |
|||
|
|||
Developer Guide |
|||
|
|||
## npm-disputes(1) |
|||
|
|||
Handling Module Name Disputes |
|||
|
|||
## npm-docs(1) |
|||
|
|||
Docs for a package in a web browser maybe |
|||
|
|||
## npm-edit(1) |
|||
|
|||
Edit an installed package |
|||
|
|||
## npm-explore(1) |
|||
|
|||
Browse an installed package |
|||
|
|||
## npm-faq(1) |
|||
|
|||
Frequently Asked Questions |
|||
|
|||
## npm-folders(1) |
|||
|
|||
Folder Structures Used by npm |
|||
|
|||
## npm-global(1) |
|||
|
|||
Folder Structures Used by npm |
|||
|
|||
## npm-help-search(1) |
|||
|
|||
Search npm help documentation |
|||
|
|||
## npm-help(1) |
|||
|
|||
Get help on npm |
|||
|
|||
## npm-init(1) |
|||
|
|||
Interactively create a package.json file |
|||
|
|||
## npm-install(1) |
|||
|
|||
Install a package |
|||
|
|||
## npm-json(1) |
|||
|
|||
Specifics of npm's package.json handling |
|||
|
|||
## npm-link(1) |
|||
|
|||
Symlink a package folder |
|||
|
|||
## npm-ls(1) |
|||
|
|||
List installed packages |
|||
|
|||
## npm-npm(1) |
|||
|
|||
node package manager |
|||
|
|||
## npm-outdated(1) |
|||
|
|||
Check for outdated packages |
|||
|
|||
## npm-owner(1) |
|||
|
|||
Manage package owners |
|||
|
|||
## npm-pack(1) |
|||
|
|||
Create a tarball from a package |
|||
|
|||
## npm-prefix(1) |
|||
|
|||
Display prefix |
|||
|
|||
## npm-prune(1) |
|||
|
|||
Remove extraneous packages |
|||
|
|||
## npm-publish(1) |
|||
|
|||
Publish a package |
|||
|
|||
## npm-rebuild(1) |
|||
|
|||
Rebuild a package |
|||
|
|||
## npm-registry(1) |
|||
|
|||
The JavaScript Package Registry |
|||
|
|||
## npm-removing-npm(1) |
|||
|
|||
Cleaning the Slate |
|||
|
|||
## npm-restart(1) |
|||
|
|||
Start a package |
|||
|
|||
## npm-rm(1) |
|||
|
|||
Remove a package |
|||
|
|||
## npm-root(1) |
|||
|
|||
Display npm root |
|||
|
|||
## npm-run-script(1) |
|||
|
|||
Run arbitrary package scripts |
|||
|
|||
## npm-scripts(1) |
|||
|
|||
How npm handles the "scripts" field |
|||
|
|||
## npm-search(1) |
|||
|
|||
Search for packages |
|||
|
|||
## npm-semver(1) |
|||
|
|||
The semantic versioner for npm |
|||
|
|||
## npm-shrinkwrap(1) |
|||
|
|||
Lock down dependency versions |
|||
|
|||
## npm-star(1) |
|||
|
|||
Mark your favorite packages |
|||
|
|||
## npm-stars(1) |
|||
|
|||
View packages marked as favorites |
|||
|
|||
## npm-start(1) |
|||
|
|||
Start a package |
|||
|
|||
## npm-stop(1) |
|||
|
|||
Stop a package |
|||
|
|||
## npm-submodule(1) |
|||
|
|||
Add a package as a git submodule |
|||
|
|||
## npm-tag(1) |
|||
|
|||
Tag a published version |
|||
|
|||
## npm-test(1) |
|||
|
|||
Test a package |
|||
|
|||
## npm-uninstall(1) |
|||
|
|||
Remove a package |
|||
|
|||
## npm-unpublish(1) |
|||
|
|||
Remove a package from the registry |
|||
|
|||
## npm-update(1) |
|||
|
|||
Update a package |
|||
|
|||
## npm-version(1) |
|||
|
|||
Bump a package version |
|||
|
|||
## npm-view(1) |
|||
|
|||
View registry info |
|||
|
|||
## npm-whoami(1) |
|||
|
|||
Display npm username |
|||
|
|||
# API Documentation |
|||
## npm-bin(3) |
|||
|
|||
Display npm bin folder |
|||
|
|||
## npm-bugs(3) |
|||
|
|||
Bugs for a package in a web browser maybe |
|||
|
|||
## npm-commands(3) |
|||
|
|||
npm commands |
|||
|
|||
## npm-config(3) |
|||
|
|||
Manage the npm configuration files |
|||
|
|||
## npm-deprecate(3) |
|||
|
|||
Deprecate a version of a package |
|||
|
|||
## npm-docs(3) |
|||
|
|||
Docs for a package in a web browser maybe |
|||
|
|||
## npm-edit(3) |
|||
|
|||
Edit an installed package |
|||
|
|||
## npm-explore(3) |
|||
|
|||
Browse an installed package |
|||
|
|||
## npm-help-search(3) |
|||
|
|||
Search the help pages |
|||
|
|||
## npm-init(3) |
|||
|
|||
Interactively create a package.json file |
|||
|
|||
## npm-install(3) |
|||
|
|||
install a package programmatically |
|||
|
|||
## npm-link(3) |
|||
|
|||
Symlink a package folder |
|||
|
|||
## npm-load(3) |
|||
|
|||
Load config settings |
|||
|
|||
## npm-ls(3) |
|||
|
|||
List installed packages |
|||
|
|||
## npm-npm(3) |
|||
|
|||
node package manager |
|||
|
|||
## npm-outdated(3) |
|||
|
|||
Check for outdated packages |
|||
|
|||
## npm-owner(3) |
|||
|
|||
Manage package owners |
|||
|
|||
## npm-pack(3) |
|||
|
|||
Create a tarball from a package |
|||
|
|||
## npm-prefix(3) |
|||
|
|||
Display prefix |
|||
|
|||
## npm-prune(3) |
|||
|
|||
Remove extraneous packages |
|||
|
|||
## npm-publish(3) |
|||
|
|||
Publish a package |
|||
|
|||
## npm-rebuild(3) |
|||
|
|||
Rebuild a package |
|||
|
|||
## npm-restart(3) |
|||
|
|||
Start a package |
|||
|
|||
## npm-root(3) |
|||
|
|||
Display npm root |
|||
|
|||
## npm-run-script(3) |
|||
|
|||
Run arbitrary package scripts |
|||
|
|||
## npm-search(3) |
|||
|
|||
Search for packages |
|||
|
|||
## npm-shrinkwrap(3) |
|||
|
|||
programmatically generate package shrinkwrap file |
|||
|
|||
## npm-start(3) |
|||
|
|||
Start a package |
|||
|
|||
## npm-stop(3) |
|||
|
|||
Stop a package |
|||
|
|||
## npm-submodule(3) |
|||
|
|||
Add a package as a git submodule |
|||
|
|||
## npm-tag(3) |
|||
|
|||
Tag a published version |
|||
|
|||
## npm-test(3) |
|||
|
|||
Test a package |
|||
|
|||
## npm-uninstall(3) |
|||
|
|||
uninstall a package programmatically |
|||
|
|||
## npm-unpublish(3) |
|||
|
|||
Remove a package from the registry |
|||
|
|||
## npm-update(3) |
|||
|
|||
Update a package |
|||
|
|||
## npm-version(3) |
|||
|
|||
Bump a package version |
|||
|
|||
## npm-view(3) |
|||
|
|||
View registry info |
|||
|
|||
## npm-whoami(3) |
|||
|
|||
Display npm username |
|||
|
|||
@ -1,25 +0,0 @@ |
|||
npm-init(1) -- Interactively create a package.json file |
|||
======================================================= |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm init |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This will ask you a bunch of questions, and then write a package.json for you. |
|||
|
|||
It attempts to make reasonable guesses about what you want things to be set to, |
|||
and then writes a package.json file with the options you've selected. |
|||
|
|||
If you already have a package.json file, it'll read that first, and default to |
|||
the options in there. |
|||
|
|||
It is strictly additive, so it does not delete options from your package.json |
|||
without a really good reason to do so. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* <https://github.com/isaacs/init-package-json> |
|||
* npm-json(1) |
|||
* npm-version(1) |
|||
@ -1,242 +0,0 @@ |
|||
npm-install(1) -- Install a package |
|||
=================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm install (with no args in a package dir) |
|||
npm install <tarball file> |
|||
npm install <tarball url> |
|||
npm install <folder> |
|||
npm install <name> [--save|--save-dev|--save-optional] |
|||
npm install <name>@<tag> |
|||
npm install <name>@<version> |
|||
npm install <name>@<version range> |
|||
npm install <name>@<version range> |
|||
|
|||
## DESCRIPTION |
|||
|
|||
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 npm-shrinkwrap(1). |
|||
|
|||
A `package` is: |
|||
|
|||
* a) a folder containing a program described by a package.json file |
|||
* b) a gzipped tarball containing (a) |
|||
* c) a url that resolves to (b) |
|||
* d) a `<name>@<version>` that is published on the registry with (c) |
|||
* e) a `<name>@<tag>` that points to (d) |
|||
* f) a `<name>` that has a "latest" tag satisfying (e) |
|||
* g) a `<git remote url>` that resolves to (b) |
|||
|
|||
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). |
|||
|
|||
|
|||
* `npm install` (in package directory, no arguments): |
|||
|
|||
Install the dependencies in the local node_modules folder. |
|||
|
|||
In global mode (ie, with `-g` or `--global` appended to the command), |
|||
it installs the current package context (ie, the current working |
|||
directory) as a global package. |
|||
|
|||
|
|||
* `npm install <folder>`: |
|||
|
|||
Install a package that is sitting in a folder on the filesystem. |
|||
|
|||
* `npm install <tarball file>`: |
|||
|
|||
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 `npm link`. |
|||
|
|||
Example: |
|||
|
|||
npm install ./package.tgz |
|||
|
|||
* `npm install <tarball url>`: |
|||
|
|||
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://" |
|||
|
|||
Example: |
|||
|
|||
npm install https://github.com/indexzero/forever/tarball/v0.5.6 |
|||
|
|||
* `npm install <name> [--save|--save-dev|--save-optional]`: |
|||
|
|||
Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See |
|||
`npm-config(1)`.) |
|||
|
|||
In most cases, this will install the latest version |
|||
of the module published on npm. |
|||
|
|||
Example: |
|||
|
|||
npm install sax |
|||
|
|||
`npm install` takes 3 exclusive, optional flags which save or update |
|||
the package version in your main package.json: |
|||
|
|||
* `--save`: Package will appear in your `dependencies`. |
|||
|
|||
* `--save-dev`: Package will appear in your `devDependencies`. |
|||
|
|||
* `--save-optional`: Package will appear in your `optionalDependencies`. |
|||
|
|||
Examples: |
|||
|
|||
npm install sax --save |
|||
npm install node-tap --save-dev |
|||
npm install dtrace-provider --save-optional |
|||
|
|||
|
|||
**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. |
|||
|
|||
* `npm install <name>@<tag>`: |
|||
|
|||
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. |
|||
|
|||
Example: |
|||
|
|||
npm install sax@latest |
|||
|
|||
* `npm install <name>@<version>`: |
|||
|
|||
Install the specified version of the package. This will fail if the version |
|||
has not been published to the registry. |
|||
|
|||
Example: |
|||
|
|||
npm install sax@0.1.1 |
|||
|
|||
* `npm install <name>@<version range>`: |
|||
|
|||
Install a version of the package matching the specified version range. This |
|||
will follow the same rules for resolving dependencies described in `npm-json(1)`. |
|||
|
|||
Note that most version ranges must be put in quotes so that your shell will |
|||
treat it as a single argument. |
|||
|
|||
Example: |
|||
|
|||
npm install sax@">=0.1.0 <0.2.0" |
|||
|
|||
* `npm install <git remote url>`: |
|||
|
|||
Install a package by cloning a git remote url. The format of the git |
|||
url is: |
|||
|
|||
<protocol>://[<user>@]<hostname><separator><path>[#<commit-ish>] |
|||
|
|||
`<protocol>` is one of `git`, `git+ssh`, `git+http`, or |
|||
`git+https`. If no `<commit-ish>` is specified, then `master` is |
|||
used. |
|||
|
|||
Examples: |
|||
|
|||
git+ssh://git@github.com:isaacs/npm.git#v1.0.27 |
|||
git+https://isaacs@github.com/isaacs/npm.git |
|||
git://github.com/isaacs/npm.git#v1.0.27 |
|||
|
|||
You may combine multiple arguments, and even multiple types of arguments. |
|||
For example: |
|||
|
|||
npm install sax@">=0.1.0 <0.2.0" bench supervisor |
|||
|
|||
The `--tag` argument will apply to all of the specified install targets. |
|||
|
|||
The `--force` argument will force npm to fetch remote resources even if a |
|||
local copy exists on disk. |
|||
|
|||
npm install sax --force |
|||
|
|||
The `--global` argument will cause npm to install the package globally |
|||
rather than locally. See `npm-folders(1)`. |
|||
|
|||
The `--link` argument will cause npm to link global installs into the |
|||
local space in some cases. |
|||
|
|||
The `--no-bin-links` argument will prevent npm from creating symlinks for |
|||
any binaries the package might contain. |
|||
|
|||
The `--no-shrinkwrap` argument, which will ignore an available |
|||
shrinkwrap file and use the package.json instead. |
|||
|
|||
The `--nodedir=/path/to/node/source` argument will allow npm to find the |
|||
node source code so that npm can compile native modules. |
|||
|
|||
See `npm-config(1)`. Many of the configuration params have some |
|||
effect on installation, since that's most of what npm does. |
|||
|
|||
## ALGORITHM |
|||
|
|||
To install a package, npm uses the following algorithm: |
|||
|
|||
install(where, what, family, ancestors) |
|||
fetch what, unpack to <where>/node_modules/<what> |
|||
for each dep in what.dependencies |
|||
resolve dep to precise version |
|||
for each dep@version in what.dependencies |
|||
not in <where>/node_modules/<what>/node_modules/* |
|||
and not in <family> |
|||
add precise version deps to <family> |
|||
install(<where>/node_modules/<what>, dep, family) |
|||
|
|||
For this `package{dep}` structure: `A{B,C}, B{C}, C{D}`, |
|||
this algorithm produces: |
|||
|
|||
A |
|||
+-- B |
|||
`-- C |
|||
`-- D |
|||
|
|||
That is, the dependency from B to C is satisfied by the fact that A |
|||
already caused C to be installed at a higher level. |
|||
|
|||
See npm-folders(1) for a more detailed description of the specific |
|||
folder structures that npm creates. |
|||
|
|||
### Limitations of npm's Install Algorithm |
|||
|
|||
There are some very rare and pathological edge-cases where a cycle can |
|||
cause npm to try to install a never-ending tree of packages. Here is |
|||
the simplest case: |
|||
|
|||
A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ... |
|||
|
|||
where `A` is some version of a package, and `A'` is a different version |
|||
of the same package. Because `B` depends on a different version of `A` |
|||
than the one that is already in the tree, it must install a separate |
|||
copy. The same is true of `A'`, which must install `B'`. Because `B'` |
|||
depends on the original version of `A`, which has been overridden, the |
|||
cycle falls into infinite regress. |
|||
|
|||
To avoid this situation, npm flat-out refuses to install any |
|||
`name@version` that is already present anywhere in the tree of package |
|||
folder ancestors. A more correct, but more complex, solution would be |
|||
to symlink the existing version into the new location. If this ever |
|||
affects a real use-case, it will be investigated. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-folders(1) |
|||
* npm-update(1) |
|||
* npm-link(1) |
|||
* npm-rebuild(1) |
|||
* npm-scripts(1) |
|||
* npm-build(1) |
|||
* npm-config(1) |
|||
* npm-registry(1) |
|||
* npm-folders(1) |
|||
* npm-tag(1) |
|||
* npm-rm(1) |
|||
* npm-shrinkwrap(1) |
|||
@ -1,587 +0,0 @@ |
|||
npm-json(1) -- Specifics of npm's package.json handling |
|||
======================================================= |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This document is all you need to know about what's required in your package.json |
|||
file. It must be actual JSON, not just a JavaScript object literal. |
|||
|
|||
A lot of the behavior described in this document is affected by the config |
|||
settings described in `npm-config(1)`. |
|||
|
|||
## DEFAULT VALUES |
|||
|
|||
npm will default some values based on package contents. |
|||
|
|||
* `"scripts": {"start": "node server.js"}` |
|||
|
|||
If there is a `server.js` file in the root of your package, then npm |
|||
will default the `start` command to `node server.js`. |
|||
|
|||
* `"scripts":{"preinstall": "node-waf clean || true; node-waf configure build"}` |
|||
|
|||
If there is a `wscript` file in the root of your package, npm will |
|||
default the `preinstall` command to compile using node-waf. |
|||
|
|||
* `"scripts":{"preinstall": "node-gyp rebuild"}` |
|||
|
|||
If there is a `binding.gyp` file in the root of your package, npm will |
|||
default the `preinstall` command to compile using node-gyp. |
|||
|
|||
* `"contributors": [...]` |
|||
|
|||
If there is an `AUTHORS` file in the root of your package, npm will |
|||
treat each line as a `Name <email> (url)` format, where email and url |
|||
are optional. Lines which start with a `#` or are blank, will be |
|||
ignored. |
|||
|
|||
## name |
|||
|
|||
The *most* important things in your package.json are the name and version fields. |
|||
Those are actually required, and your package won't install without |
|||
them. The name and version together form an identifier that is assumed |
|||
to be completely unique. Changes to the package should come along with |
|||
changes to the version. |
|||
|
|||
The name is what your thing is called. Some tips: |
|||
|
|||
* Don't put "js" or "node" in the name. It's assumed that it's js, since you're |
|||
writing a package.json file, and you can specify the engine using the "engines" |
|||
field. (See below.) |
|||
* The name ends up being part of a URL, an argument on the command line, and a |
|||
folder name. Any name with non-url-safe characters will be rejected. |
|||
Also, it can't start with a dot or an underscore. |
|||
* The name will probably be passed as an argument to require(), so it should |
|||
be something short, but also reasonably descriptive. |
|||
* You may want to check the npm registry to see if there's something by that name |
|||
already, before you get too attached to it. http://registry.npmjs.org/ |
|||
|
|||
## version |
|||
|
|||
The *most* important things in your package.json are the name and version fields. |
|||
Those are actually required, and your package won't install without |
|||
them. The name and version together form an identifier that is assumed |
|||
to be completely unique. Changes to the package should come along with |
|||
changes to the version. |
|||
|
|||
Version must be parseable by |
|||
[node-semver](https://github.com/isaacs/node-semver), which is bundled |
|||
with npm as a dependency. (`npm install semver` to use it yourself.) |
|||
|
|||
Here's how npm's semver implementation deviates from what's on semver.org: |
|||
|
|||
* Versions can start with "v" |
|||
* A numeric item separated from the main three-number version by a hyphen |
|||
will be interpreted as a "build" number, and will *increase* the version. |
|||
But, if the tag is not a number separated by a hyphen, then it's treated |
|||
as a pre-release tag, and is *less than* the version without a tag. |
|||
So, `0.1.2-7 > 0.1.2-7-beta > 0.1.2-6 > 0.1.2 > 0.1.2beta` |
|||
|
|||
This is a little bit confusing to explain, but matches what you see in practice |
|||
when people create tags in git like "v1.2.3" and then do "git describe" to generate |
|||
a patch version. |
|||
|
|||
## description |
|||
|
|||
Put a description in it. It's a string. This helps people discover your |
|||
package, as it's listed in `npm search`. |
|||
|
|||
## keywords |
|||
|
|||
Put keywords in it. It's an array of strings. This helps people |
|||
discover your package as it's listed in `npm search`. |
|||
|
|||
## homepage |
|||
|
|||
The url to the project homepage. |
|||
|
|||
**NOTE**: This is *not* the same as "url". If you put a "url" field, |
|||
then the registry will think it's a redirection to your package that has |
|||
been published somewhere else, and spit at you. |
|||
|
|||
Literally. Spit. I'm so not kidding. |
|||
|
|||
## bugs |
|||
|
|||
The url to your project's issue tracker and / or the email address to which |
|||
issues should be reported. These are helpful for people who encounter issues |
|||
with your package. |
|||
|
|||
It should look like this: |
|||
|
|||
{ "url" : "http://github.com/owner/project/issues" |
|||
, "email" : "project@hostname.com" |
|||
} |
|||
|
|||
You can specify either one or both values. If you want to provide only a url, |
|||
you can specify the value for "bugs" as a simple string instead of an object. |
|||
|
|||
If a url is provided, it will be used by the `npm bugs` command. |
|||
|
|||
## license |
|||
|
|||
You should specify a license for your package so that people know how they are |
|||
permitted to use it, and any restrictions you're placing on it. |
|||
|
|||
The simplest way, assuming you're using a common license such as BSD or MIT, is |
|||
to just specify the name of the license you're using, like this: |
|||
|
|||
{ "license" : "BSD" } |
|||
|
|||
If you have more complex licensing terms, or you want to provide more detail |
|||
in your package.json file, you can use the more verbose plural form, like this: |
|||
|
|||
"licenses" : [ |
|||
{ "type" : "MyLicense" |
|||
, "url" : "http://github.com/owner/project/path/to/license" |
|||
} |
|||
] |
|||
|
|||
It's also a good idea to include a license file at the top level in your package. |
|||
|
|||
## people fields: author, contributors |
|||
|
|||
The "author" is one person. "contributors" is an array of people. A "person" |
|||
is an object with a "name" field and optionally "url" and "email", like this: |
|||
|
|||
{ "name" : "Barney Rubble" |
|||
, "email" : "b@rubble.com" |
|||
, "url" : "http://barnyrubble.tumblr.com/" |
|||
} |
|||
|
|||
Or you can shorten that all into a single string, and npm will parse it for you: |
|||
|
|||
"Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/) |
|||
|
|||
Both email and url are optional either way. |
|||
|
|||
npm also sets a top-level "maintainers" field with your npm user info. |
|||
|
|||
## files |
|||
|
|||
The "files" field is an array of files to include in your project. If |
|||
you name a folder in the array, then it will also include the files |
|||
inside that folder. (Unless they would be ignored by another rule.) |
|||
|
|||
You can also provide a ".npmignore" file in the root of your package, |
|||
which will keep files from being included, even if they would be picked |
|||
up by the files array. The ".npmignore" file works just like a |
|||
".gitignore". |
|||
|
|||
## main |
|||
|
|||
The main field is a module ID that is the primary entry point to your program. |
|||
That is, if your package is named `foo`, and a user installs it, and then does |
|||
`require("foo")`, then your main module's exports object will be returned. |
|||
|
|||
This should be a module ID relative to the root of your package folder. |
|||
|
|||
For most modules, it makes the most sense to have a main script and often not |
|||
much else. |
|||
|
|||
## bin |
|||
|
|||
A lot of packages have one or more executable files that they'd like to |
|||
install into the PATH. npm makes this pretty easy (in fact, it uses this |
|||
feature to install the "npm" executable.) |
|||
|
|||
To use this, supply a `bin` field in your package.json which is a map of |
|||
command name to local file name. On install, npm will symlink that file into |
|||
`prefix/bin` for global installs, or `./node_modules/.bin/` for local |
|||
installs. |
|||
|
|||
|
|||
For example, npm has this: |
|||
|
|||
{ "bin" : { "npm" : "./cli.js" } } |
|||
|
|||
So, when you install npm, it'll create a symlink from the `cli.js` script to |
|||
`/usr/local/bin/npm`. |
|||
|
|||
If you have a single executable, and its name should be the name |
|||
of the package, then you can just supply it as a string. For example: |
|||
|
|||
{ "name": "my-program" |
|||
, "version": "1.2.5" |
|||
, "bin": "./path/to/program" } |
|||
|
|||
would be the same as this: |
|||
|
|||
{ "name": "my-program" |
|||
, "version": "1.2.5" |
|||
, "bin" : { "my-program" : "./path/to/program" } } |
|||
|
|||
## man |
|||
|
|||
Specify either a single file or an array of filenames to put in place for the |
|||
`man` program to find. |
|||
|
|||
If only a single file is provided, then it's installed such that it is the |
|||
result from `man <pkgname>`, regardless of its actual filename. For example: |
|||
|
|||
{ "name" : "foo" |
|||
, "version" : "1.2.3" |
|||
, "description" : "A packaged foo fooer for fooing foos" |
|||
, "main" : "foo.js" |
|||
, "man" : "./man/doc.1" |
|||
} |
|||
|
|||
would link the `./man/doc.1` file in such that it is the target for `man foo` |
|||
|
|||
If the filename doesn't start with the package name, then it's prefixed. |
|||
So, this: |
|||
|
|||
{ "name" : "foo" |
|||
, "version" : "1.2.3" |
|||
, "description" : "A packaged foo fooer for fooing foos" |
|||
, "main" : "foo.js" |
|||
, "man" : [ "./man/foo.1", "./man/bar.1" ] |
|||
} |
|||
|
|||
will create files to do `man foo` and `man foo-bar`. |
|||
|
|||
Man files must end with a number, and optionally a `.gz` suffix if they are |
|||
compressed. The number dictates which man section the file is installed into. |
|||
|
|||
{ "name" : "foo" |
|||
, "version" : "1.2.3" |
|||
, "description" : "A packaged foo fooer for fooing foos" |
|||
, "main" : "foo.js" |
|||
, "man" : [ "./man/foo.1", "./man/foo.2" ] |
|||
} |
|||
|
|||
will create entries for `man foo` and `man 2 foo` |
|||
|
|||
## directories |
|||
|
|||
The CommonJS [Packages](http://wiki.commonjs.org/wiki/Packages/1.0) spec details a |
|||
few ways that you can indicate the structure of your package using a `directories` |
|||
hash. If you look at [npm's package.json](http://registry.npmjs.org/npm/latest), |
|||
you'll see that it has directories for doc, lib, and man. |
|||
|
|||
In the future, this information may be used in other creative ways. |
|||
|
|||
### directories.lib |
|||
|
|||
Tell people where the bulk of your library is. Nothing special is done |
|||
with the lib folder in any way, but it's useful meta info. |
|||
|
|||
### directories.bin |
|||
|
|||
If you specify a "bin" directory, then all the files in that folder will |
|||
be used as the "bin" hash. |
|||
|
|||
If you have a "bin" hash already, then this has no effect. |
|||
|
|||
### directories.man |
|||
|
|||
A folder that is full of man pages. Sugar to generate a "man" array by |
|||
walking the folder. |
|||
|
|||
### directories.doc |
|||
|
|||
Put markdown files in here. Eventually, these will be displayed nicely, |
|||
maybe, someday. |
|||
|
|||
### directories.example |
|||
|
|||
Put example scripts in here. Someday, it might be exposed in some clever way. |
|||
|
|||
## repository |
|||
|
|||
Specify the place where your code lives. This is helpful for people who |
|||
want to contribute. If the git repo is on github, then the `npm docs` |
|||
command will be able to find you. |
|||
|
|||
Do it like this: |
|||
|
|||
"repository" : |
|||
{ "type" : "git" |
|||
, "url" : "http://github.com/isaacs/npm.git" |
|||
} |
|||
|
|||
"repository" : |
|||
{ "type" : "svn" |
|||
, "url" : "http://v8.googlecode.com/svn/trunk/" |
|||
} |
|||
|
|||
The URL should be a publicly available (perhaps read-only) url that can be handed |
|||
directly to a VCS program without any modification. It should not be a url to an |
|||
html project page that you put in your browser. It's for computers. |
|||
|
|||
## scripts |
|||
|
|||
The "scripts" member is an object hash of script commands that are run |
|||
at various times in the lifecycle of your package. The key is the lifecycle |
|||
event, and the value is the command to run at that point. |
|||
|
|||
See `npm-scripts(1)` to find out more about writing package scripts. |
|||
|
|||
## config |
|||
|
|||
A "config" hash can be used to set configuration |
|||
parameters used in package scripts that persist across upgrades. For |
|||
instance, if a package had the following: |
|||
|
|||
{ "name" : "foo" |
|||
, "config" : { "port" : "8080" } } |
|||
|
|||
and then had a "start" command that then referenced the |
|||
`npm_package_config_port` environment variable, then the user could |
|||
override that by doing `npm config set foo:port 8001`. |
|||
|
|||
See `npm-config(1)` and `npm-scripts(1)` for more on package |
|||
configs. |
|||
|
|||
## dependencies |
|||
|
|||
Dependencies are specified with a simple hash of package name to version |
|||
range. The version range is EITHER a string which has one or more |
|||
space-separated descriptors, OR a range like "fromVersion - toVersion" |
|||
|
|||
**Please do not put test harnesses in your `dependencies` hash.** See |
|||
`devDependencies`, below. |
|||
|
|||
Version range descriptors may be any of the following styles, where "version" |
|||
is a semver compatible version identifier. |
|||
|
|||
* `version` Must match `version` exactly |
|||
* `=version` Same as just `version` |
|||
* `>version` Must be greater than `version` |
|||
* `>=version` etc |
|||
* `<version` |
|||
* `<=version` |
|||
* `~version` See 'Tilde Version Ranges' below |
|||
* `1.2.x` See 'X Version Ranges' below |
|||
* `http://...` See 'URLs as Dependencies' below |
|||
* `*` Matches any version |
|||
* `""` (just an empty string) Same as `*` |
|||
* `version1 - version2` Same as `>=version1 <=version2`. |
|||
* `range1 || range2` Passes if either range1 or range2 are satisfied. |
|||
* `git...` See 'Git URLs as Dependencies' below |
|||
|
|||
For example, these are all valid: |
|||
|
|||
{ "dependencies" : |
|||
{ "foo" : "1.0.0 - 2.9999.9999" |
|||
, "bar" : ">=1.0.2 <2.1.2" |
|||
, "baz" : ">1.0.2 <=2.3.4" |
|||
, "boo" : "2.0.1" |
|||
, "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0" |
|||
, "asd" : "http://asdf.com/asdf.tar.gz" |
|||
, "til" : "~1.2" |
|||
, "elf" : "~1.2.3" |
|||
, "two" : "2.x" |
|||
, "thr" : "3.3.x" |
|||
} |
|||
} |
|||
|
|||
### Tilde Version Ranges |
|||
|
|||
A range specifier starting with a tilde `~` character is matched against |
|||
a version in the following fashion. |
|||
|
|||
* The version must be at least as high as the range. |
|||
* The version must be less than the next major revision above the range. |
|||
|
|||
For example, the following are equivalent: |
|||
|
|||
* `"~1.2.3" = ">=1.2.3 <1.3.0"` |
|||
* `"~1.2" = ">=1.2.0 <1.3.0"` |
|||
* `"~1" = ">=1.0.0 <1.1.0"` |
|||
|
|||
### X Version Ranges |
|||
|
|||
An "x" in a version range specifies that the version number must start |
|||
with the supplied digits, but any digit may be used in place of the x. |
|||
|
|||
The following are equivalent: |
|||
|
|||
* `"1.2.x" = ">=1.2.0 <1.3.0"` |
|||
* `"1.x.x" = ">=1.0.0 <2.0.0"` |
|||
* `"1.2" = "1.2.x"` |
|||
* `"1.x" = "1.x.x"` |
|||
* `"1" = "1.x.x"` |
|||
|
|||
You may not supply a comparator with a version containing an x. Any |
|||
digits after the first "x" are ignored. |
|||
|
|||
### URLs as Dependencies |
|||
|
|||
Starting with npm version 0.2.14, you may specify a tarball URL in place |
|||
of a version range. |
|||
|
|||
This tarball will be downloaded and installed locally to your package at |
|||
install time. |
|||
|
|||
### Git URLs as Dependencies |
|||
|
|||
Git urls can be of the form: |
|||
|
|||
git://github.com/user/project.git#commit-ish |
|||
git+ssh://user@hostname:project.git#commit-ish |
|||
git+ssh://user@hostname/project.git#commit-ish |
|||
git+http://user@hostname/project/blah.git#commit-ish |
|||
git+https://user@hostname/project/blah.git#commit-ish |
|||
|
|||
The `commit-ish` can be any tag, sha, or branch which can be supplied as |
|||
an argument to `git checkout`. The default is `master`. |
|||
|
|||
## devDependencies |
|||
|
|||
If someone is planning on downloading and using your module in their |
|||
program, then they probably don't want or need to download and build |
|||
the external test or documentation framework that you use. |
|||
|
|||
In this case, it's best to list these additional items in a |
|||
`devDependencies` hash. |
|||
|
|||
These things will be installed whenever the `--dev` configuration flag |
|||
is set. This flag is set automatically when doing `npm link` or when doing |
|||
`npm install` from the root of a package, and can be managed like any other npm |
|||
configuration param. See `npm-config(1)` for more on the topic. |
|||
|
|||
## bundledDependencies |
|||
|
|||
Array of package names that will be bundled when publishing the package. |
|||
|
|||
If this is spelled `"bundleDependencies"`, then that is also honorable. |
|||
|
|||
## optionalDependencies |
|||
|
|||
If a dependency can be used, but you would like npm to proceed if it |
|||
cannot be found or fails to install, then you may put it in the |
|||
`optionalDependencies` hash. This is a map of package name to version |
|||
or url, just like the `dependencies` hash. The difference is that |
|||
failure is tolerated. |
|||
|
|||
It is still your program's responsibility to handle the lack of the |
|||
dependency. For example, something like this: |
|||
|
|||
try { |
|||
var foo = require('foo') |
|||
var fooVersion = require('foo/package.json').version |
|||
} catch (er) { |
|||
foo = null |
|||
} |
|||
if ( notGoodFooVersion(fooVersion) ) { |
|||
foo = null |
|||
} |
|||
|
|||
// .. then later in your program .. |
|||
|
|||
if (foo) { |
|||
foo.doFooThings() |
|||
} |
|||
|
|||
Entries in `optionalDependencies` will override entries of the same name in |
|||
`dependencies`, so it's usually best to only put in one place. |
|||
|
|||
## engines |
|||
|
|||
You can specify the version of node that your stuff works on: |
|||
|
|||
{ "engines" : { "node" : ">=0.1.27 <0.1.30" } } |
|||
|
|||
And, like with dependencies, if you don't specify the version (or if you |
|||
specify "\*" as the version), then any version of node will do. |
|||
|
|||
If you specify an "engines" field, then npm will require that "node" be |
|||
somewhere on that list. If "engines" is omitted, then npm will just assume |
|||
that it works on node. |
|||
|
|||
You can also use the "engines" field to specify which versions of npm |
|||
are capable of properly installing your program. For example: |
|||
|
|||
{ "engines" : { "npm" : "~1.0.20" } } |
|||
|
|||
Note that, unless the user has set the `engine-strict` config flag, this |
|||
field is advisory only. |
|||
|
|||
## engineStrict |
|||
|
|||
If you are sure that your module will *definitely not* run properly on |
|||
versions of Node/npm other than those specified in the `engines` hash, |
|||
then you can set `"engineStrict": true` in your package.json file. |
|||
This will override the user's `engine-strict` config setting. |
|||
|
|||
Please do not do this unless you are really very very sure. If your |
|||
engines hash is something overly restrictive, you can quite easily and |
|||
inadvertently lock yourself into obscurity and prevent your users from |
|||
updating to new versions of Node. Consider this choice carefully. If |
|||
people abuse it, it will be removed in a future version of npm. |
|||
|
|||
## os |
|||
|
|||
You can specify which operating systems your |
|||
module will run on: |
|||
|
|||
"os" : [ "darwin", "linux" ] |
|||
|
|||
You can also blacklist instead of whitelist operating systems, |
|||
just prepend the blacklisted os with a '!': |
|||
|
|||
"os" : [ "!win32" ] |
|||
|
|||
The host operating system is determined by `process.platform` |
|||
|
|||
It is allowed to both blacklist, and whitelist, although there isn't any |
|||
good reason to do this. |
|||
|
|||
## cpu |
|||
|
|||
If your code only runs on certain cpu architectures, |
|||
you can specify which ones. |
|||
|
|||
"cpu" : [ "x64", "ia32" ] |
|||
|
|||
Like the `os` option, you can also blacklist architectures: |
|||
|
|||
"cpu" : [ "!arm", "!mips" ] |
|||
|
|||
The host architecture is determined by `process.arch` |
|||
|
|||
## preferGlobal |
|||
|
|||
If your package is primarily a command-line application that should be |
|||
installed globally, then set this value to `true` to provide a warning |
|||
if it is installed locally. |
|||
|
|||
It doesn't actually prevent users from installing it locally, but it |
|||
does help prevent some confusion if it doesn't work as expected. |
|||
|
|||
## private |
|||
|
|||
If you set `"private": true` in your package.json, then npm will refuse |
|||
to publish it. |
|||
|
|||
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 `publishConfig` hash described below |
|||
to override the `registry` config param at publish-time. |
|||
|
|||
## publishConfig |
|||
|
|||
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. |
|||
|
|||
Any config values can be overridden, but of course only "tag" and |
|||
"registry" probably matter for the purposes of publishing. |
|||
|
|||
See `npm-config(1)` to see the list of config options that can be |
|||
overridden. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-semver(1) |
|||
* npm-init(1) |
|||
* npm-version(1) |
|||
* npm-config(1) |
|||
* npm-help(1) |
|||
* npm-faq(1) |
|||
* npm-install(1) |
|||
* npm-publish(1) |
|||
* npm-rm(1) |
|||
@ -1,60 +0,0 @@ |
|||
npm-link(1) -- Symlink a package folder |
|||
======================================= |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm link (in package folder) |
|||
npm link <pkgname> |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Package linking is a two-step process. |
|||
|
|||
First, `npm link` in a package folder will create a globally-installed |
|||
symbolic link from `prefix/package-name` to the current folder. |
|||
|
|||
Next, in some other location, `npm link package-name` will create a |
|||
symlink from the local `node_modules` folder to the global symlink. |
|||
|
|||
Note that `package-name` is taken from `package.json` , |
|||
not from directory name. |
|||
|
|||
When creating tarballs for `npm publish`, the linked packages are |
|||
"snapshotted" to their current state by resolving the symbolic links. |
|||
|
|||
This is |
|||
handy for installing your own stuff, so that you can work on it and test it |
|||
iteratively without having to continually rebuild. |
|||
|
|||
For example: |
|||
|
|||
cd ~/projects/node-redis # go into the package directory |
|||
npm link # creates global link |
|||
cd ~/projects/node-bloggy # go into some other package directory. |
|||
npm link redis # link-install the package |
|||
|
|||
Now, any changes to ~/projects/node-redis will be reflected in |
|||
~/projects/node-bloggy/node_modules/redis/ |
|||
|
|||
You may also shortcut the two steps in one. For example, to do the |
|||
above use-case in a shorter way: |
|||
|
|||
cd ~/projects/node-bloggy # go into the dir of your main project |
|||
npm link ../node-redis # link the dir of your dependency |
|||
|
|||
The second line is the equivalent of doing: |
|||
|
|||
(cd ../node-redis; npm link) |
|||
npm link redis |
|||
|
|||
That is, it first creates a global link, and then links the global |
|||
installation target into your project's `node_modules` folder. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-developers(1) |
|||
* npm-faq(1) |
|||
* npm-json(1) |
|||
* npm-install(1) |
|||
* npm-folders(1) |
|||
* npm-config(1) |
|||
@ -1,68 +0,0 @@ |
|||
npm-ls(1) -- List installed packages |
|||
====================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm list [<pkg> ...] |
|||
npm ls [<pkg> ...] |
|||
npm la [<pkg> ...] |
|||
npm ll [<pkg> ...] |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This command will print to stdout all the versions of packages that are |
|||
installed, as well as their dependencies, in a tree-structure. |
|||
|
|||
Positional arguments are `name@version-range` identifiers, which will |
|||
limit the results to only the paths to the packages named. Note that |
|||
nested packages will *also* show the paths to the specified packages. |
|||
For example, running `npm ls promzard` in npm's source tree will show: |
|||
|
|||
npm@@VERSION@ /path/to/npm |
|||
└─┬ init-package-json@0.0.4 |
|||
└── promzard@0.1.5 |
|||
|
|||
It will show print out extraneous, missing, and invalid packages. |
|||
|
|||
When run as `ll` or `la`, it shows extended information by default. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### json |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Show information in JSON format. |
|||
|
|||
### long |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Show extended information. |
|||
|
|||
### parseable |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Show parseable output instead of tree view. |
|||
|
|||
### global |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
List packages in the global install prefix instead of in the current |
|||
project. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-config(1) |
|||
* npm-folders(1) |
|||
* npm-install(1) |
|||
* npm-link(1) |
|||
* npm-prune(1) |
|||
* npm-outdated(1) |
|||
* npm-update(1) |
|||
@ -0,0 +1,38 @@ |
|||
npm-adduser(1) -- Add a registry user account |
|||
============================================= |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm adduser |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Create or verify a user named `<username>` in the npm registry, and |
|||
save the credentials to the `.npmrc` file. |
|||
|
|||
The username, password, and email are read in from prompts. |
|||
|
|||
You may use this command to change your email address, but not username |
|||
or password. |
|||
|
|||
To reset your password, go to <http://admin.npmjs.org/> |
|||
|
|||
You may use this command multiple times with the same user account to |
|||
authorize on a new machine. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### registry |
|||
|
|||
Default: http://registry.npmjs.org/ |
|||
|
|||
The base URL of the npm package registry. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-registry(7) |
|||
* npm-config(1) |
|||
* npm-config(7) |
|||
* npmrc(5) |
|||
* npm-owner(1) |
|||
* npm-whoami(1) |
|||
@ -0,0 +1,19 @@ |
|||
npm-bin(1) -- Display npm bin folder |
|||
==================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm bin |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Print the folder where npm will install executables. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-prefix(1) |
|||
* npm-root(1) |
|||
* npm-folders(7) |
|||
* npm-config(1) |
|||
* npm-config(7) |
|||
* npmrc(5) |
|||
@ -0,0 +1,40 @@ |
|||
npm-bugs(1) -- Bugs for a package in a web browser maybe |
|||
======================================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm bugs <pkgname> |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This command tries to guess at the likely location of a package's |
|||
bug tracker URL, and then tries to open it using the `--browser` |
|||
config param. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### browser |
|||
|
|||
* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` |
|||
* Type: String |
|||
|
|||
The browser that is called by the `npm bugs` command to open websites. |
|||
|
|||
### registry |
|||
|
|||
* Default: https://registry.npmjs.org/ |
|||
* Type: url |
|||
|
|||
The base URL of the npm package registry. |
|||
|
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-docs(1) |
|||
* npm-view(1) |
|||
* npm-publish(1) |
|||
* npm-registry(7) |
|||
* npm-config(1) |
|||
* npm-config(7) |
|||
* npmrc(5) |
|||
* package.json(5) |
|||
@ -0,0 +1,22 @@ |
|||
npm-build(1) -- Build a package |
|||
=============================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm build <package-folder> |
|||
|
|||
* `<package-folder>`: |
|||
A folder containing a `package.json` file in its root. |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This is the plumbing command called by `npm link` and `npm install`. |
|||
|
|||
It should generally not be called directly. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-install(1) |
|||
* npm-link(1) |
|||
* npm-scripts(7) |
|||
* package.json(5) |
|||
@ -0,0 +1,72 @@ |
|||
npm-cache(1) -- Manipulates packages cache |
|||
========================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm cache add <tarball file> |
|||
npm cache add <folder> |
|||
npm cache add <tarball url> |
|||
npm cache add <name>@<version> |
|||
|
|||
npm cache ls [<path>] |
|||
|
|||
npm cache clean [<path>] |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Used to add, list, or clear the npm cache folder. |
|||
|
|||
* add: |
|||
Add the specified package to the local cache. This command is primarily |
|||
intended to be used internally by npm, but it can provide a way to |
|||
add data to the local installation cache explicitly. |
|||
|
|||
* ls: |
|||
Show the data in the cache. Argument is a path to show in the cache |
|||
folder. Works a bit like the `find` program, but limited by the |
|||
`depth` config. |
|||
|
|||
* clean: |
|||
Delete data out of the cache folder. If an argument is provided, then |
|||
it specifies a subpath to delete. If no argument is provided, then |
|||
the entire cache is cleared. |
|||
|
|||
## DETAILS |
|||
|
|||
npm stores cache data in `$HOME/.npm`. For each package that is added |
|||
to the cache, three pieces of information are stored in |
|||
`{cache}/{name}/{version}`: |
|||
|
|||
* .../package/: |
|||
A folder containing the package contents as they appear in the tarball. |
|||
* .../package.json: |
|||
The package.json file, as npm sees it, with overlays applied and a _id attribute. |
|||
* .../package.tgz: |
|||
The tarball for that version. |
|||
|
|||
Additionally, whenever a registry request is made, a `.cache.json` file |
|||
is placed at the corresponding URI, to store the ETag and the requested |
|||
data. |
|||
|
|||
Commands that make non-essential registry requests (such as `search` and |
|||
`view`, or the completion scripts) generally specify a minimum timeout. |
|||
If the `.cache.json` file is younger than the specified timeout, then |
|||
they do not make an HTTP request to the registry. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### cache |
|||
|
|||
Default: `$HOME/.npm` on Posix, or `$HOME/npm-cache` on Windows. |
|||
|
|||
The root cache folder. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-folders(7) |
|||
* npm-config(1) |
|||
* npm-config(7) |
|||
* npmrc(5) |
|||
* npm-install(1) |
|||
* npm-publish(1) |
|||
* npm-pack(1) |
|||
@ -0,0 +1,29 @@ |
|||
npm-completion(1) -- Tab Completion for npm |
|||
=========================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
. <(npm completion) |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Enables tab-completion in all npm commands. |
|||
|
|||
The synopsis above |
|||
loads the completions into your current shell. Adding it to |
|||
your ~/.bashrc or ~/.zshrc will make the completions available |
|||
everywhere. |
|||
|
|||
You may of course also pipe the output of npm completion to a file |
|||
such as `/usr/local/etc/bash_completion.d/npm` if you have a system |
|||
that will read that file for you. |
|||
|
|||
When `COMP_CWORD`, `COMP_LINE`, and `COMP_POINT` are defined in the |
|||
environment, `npm completion` acts in "plumbing mode", and outputs |
|||
completions based on the arguments. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-developers(7) |
|||
* npm-faq(7) |
|||
* npm(1) |
|||
@ -0,0 +1,70 @@ |
|||
npm-config(1) -- Manage the npm configuration files |
|||
=================================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm config set <key> <value> [--global] |
|||
npm config get <key> |
|||
npm config delete <key> |
|||
npm config list |
|||
npm config edit |
|||
npm get <key> |
|||
npm set <key> <value> [--global] |
|||
|
|||
## DESCRIPTION |
|||
|
|||
npm gets its config settings from the command line, environment |
|||
variables, `npmrc` files, and in some cases, the `package.json` file. |
|||
|
|||
See npmrc(5) for more information about the npmrc files. |
|||
|
|||
See `npm-config(7)` for a more thorough discussion of the mechanisms |
|||
involved. |
|||
|
|||
The `npm config` command can be used to update and edit the contents |
|||
of the user and global npmrc files. |
|||
|
|||
## Sub-commands |
|||
|
|||
Config supports the following sub-commands: |
|||
|
|||
### set |
|||
|
|||
npm config set key value |
|||
|
|||
Sets the config key to the value. |
|||
|
|||
If value is omitted, then it sets it to "true". |
|||
|
|||
### get |
|||
|
|||
npm config get key |
|||
|
|||
Echo the config value to stdout. |
|||
|
|||
### list |
|||
|
|||
npm config list |
|||
|
|||
Show all the config settings. |
|||
|
|||
### delete |
|||
|
|||
npm config delete key |
|||
|
|||
Deletes the key from all configuration files. |
|||
|
|||
### edit |
|||
|
|||
npm config edit |
|||
|
|||
Opens the config file in an editor. Use the `--global` flag to edit the |
|||
global config. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-folders(5) |
|||
* npm-config(7) |
|||
* package.json(5) |
|||
* npmrc(5) |
|||
* npm(1) |
|||
@ -0,0 +1,26 @@ |
|||
npm-deprecate(1) -- Deprecate a version of a package |
|||
==================================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm deprecate <name>[@<version>] <message> |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This command will update the npm registry entry for a package, providing |
|||
a deprecation warning to all who attempt to install it. |
|||
|
|||
It works on version ranges as well as specific versions, so you can do |
|||
something like this: |
|||
|
|||
npm deprecate my-thing@"< 0.2.3" "critical bug fixed in v0.2.3" |
|||
|
|||
Note that you must be the package owner to deprecate something. See the |
|||
`owner` and `adduser` help topics. |
|||
|
|||
To un-deprecate a package, specify an empty string (`""`) for the `message` argument. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-publish(1) |
|||
* npm-registry(7) |
|||
@ -0,0 +1,40 @@ |
|||
npm-docs(1) -- Docs for a package in a web browser maybe |
|||
======================================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm docs <pkgname> |
|||
npm home <pkgname> |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This command tries to guess at the likely location of a package's |
|||
documentation URL, and then tries to open it using the `--browser` |
|||
config param. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### browser |
|||
|
|||
* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"` |
|||
* Type: String |
|||
|
|||
The browser that is called by the `npm docs` command to open websites. |
|||
|
|||
### registry |
|||
|
|||
* Default: https://registry.npmjs.org/ |
|||
* Type: url |
|||
|
|||
The base URL of the npm package registry. |
|||
|
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-view(1) |
|||
* npm-publish(1) |
|||
* npm-registry(7) |
|||
* npm-config(1) |
|||
* npm-config(7) |
|||
* npmrc(5) |
|||
* package.json(5) |
|||
@ -0,0 +1,37 @@ |
|||
npm-edit(1) -- Edit an installed package |
|||
======================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm edit <name>[@<version>] |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Opens the package folder in the default editor (or whatever you've |
|||
configured as the npm `editor` config -- see `npm-config(7)`.) |
|||
|
|||
After it has been edited, the package is rebuilt so as to pick up any |
|||
changes in compiled packages. |
|||
|
|||
For instance, you can do `npm install connect` to install connect |
|||
into your package, and then `npm edit connect` to make a few |
|||
changes to your locally installed copy. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### editor |
|||
|
|||
* Default: `EDITOR` environment variable if set, or `"vi"` on Posix, |
|||
or `"notepad"` on Windows. |
|||
* Type: path |
|||
|
|||
The command to run for `npm edit` or `npm config edit`. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-folders(7) |
|||
* npm-explore(1) |
|||
* npm-install(1) |
|||
* npm-config(1) |
|||
* npm-config(7) |
|||
* npmrc(5) |
|||
@ -0,0 +1,40 @@ |
|||
npm-explore(1) -- Browse an installed package |
|||
============================================= |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm explore <name>[@<version>] [ -- <cmd>] |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Spawn a subshell in the directory of the installed package specified. |
|||
|
|||
If a command is specified, then it is run in the subshell, which then |
|||
immediately terminates. |
|||
|
|||
This is particularly handy in the case of git submodules in the |
|||
`node_modules` folder: |
|||
|
|||
npm explore some-dependency -- git pull origin master |
|||
|
|||
Note that the package is *not* automatically rebuilt afterwards, so be |
|||
sure to use `npm rebuild <pkg>` if you make any changes. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### shell |
|||
|
|||
* Default: SHELL environment variable, or "bash" on Posix, or "cmd" on |
|||
Windows |
|||
* Type: path |
|||
|
|||
The shell to run for the `npm explore` command. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-submodule(1) |
|||
* npm-folders(7) |
|||
* npm-edit(1) |
|||
* npm-rebuild(1) |
|||
* npm-build(1) |
|||
* npm-install(1) |
|||
@ -0,0 +1,35 @@ |
|||
npm-help-search(1) -- Search npm help documentation |
|||
=================================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm help-search some search terms |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This command will search the npm markdown documentation files for the |
|||
terms provided, and then list the results, sorted by relevance. |
|||
|
|||
If only one result is found, then it will show that help topic. |
|||
|
|||
If the argument to `npm help` is not a known help topic, then it will |
|||
call `help-search`. It is rarely if ever necessary to call this |
|||
command directly. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### long |
|||
|
|||
* Type: Boolean |
|||
* Default false |
|||
|
|||
If true, the "long" flag will cause help-search to output context around |
|||
where the terms were found in the documentation. |
|||
|
|||
If false, then help-search will just list out the help topics found. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm(1) |
|||
* npm-faq(7) |
|||
* npm-help(1) |
|||
@ -0,0 +1,40 @@ |
|||
npm-help(1) -- Get help on npm |
|||
============================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm help <topic> |
|||
npm help some search terms |
|||
|
|||
## DESCRIPTION |
|||
|
|||
If supplied a topic, then show the appropriate documentation page. |
|||
|
|||
If the topic does not exist, or if multiple terms are provided, then run |
|||
the `help-search` command to find a match. Note that, if `help-search` |
|||
finds a single subject, then it will run `help` on that topic, so unique |
|||
matches are equivalent to specifying a topic name. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### viewer |
|||
|
|||
* Default: "man" on Posix, "browser" on Windows |
|||
* Type: path |
|||
|
|||
The program to use to view help content. |
|||
|
|||
Set to `"browser"` to view html help content in the default web browser. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm(1) |
|||
* README |
|||
* npm-faq(7) |
|||
* npm-folders(7) |
|||
* npm-config(1) |
|||
* npm-config(7) |
|||
* npmrc(5) |
|||
* package.json(5) |
|||
* npm-help-search(1) |
|||
* npm-index(7) |
|||
@ -0,0 +1,25 @@ |
|||
npm-init(1) -- Interactively create a package.json file |
|||
======================================================= |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm init |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This will ask you a bunch of questions, and then write a package.json for you. |
|||
|
|||
It attempts to make reasonable guesses about what you want things to be set to, |
|||
and then writes a package.json file with the options you've selected. |
|||
|
|||
If you already have a package.json file, it'll read that first, and default to |
|||
the options in there. |
|||
|
|||
It is strictly additive, so it does not delete options from your package.json |
|||
without a really good reason to do so. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* <https://github.com/isaacs/init-package-json> |
|||
* package.json(5) |
|||
* npm-version(1) |
|||
@ -0,0 +1,244 @@ |
|||
npm-install(1) -- Install a package |
|||
=================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm install (with no args in a package dir) |
|||
npm install <tarball file> |
|||
npm install <tarball url> |
|||
npm install <folder> |
|||
npm install <name> [--save|--save-dev|--save-optional] |
|||
npm install <name>@<tag> |
|||
npm install <name>@<version> |
|||
npm install <name>@<version range> |
|||
npm install <name>@<version range> |
|||
|
|||
## DESCRIPTION |
|||
|
|||
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 npm-shrinkwrap(1). |
|||
|
|||
A `package` is: |
|||
|
|||
* a) a folder containing a program described by a package.json file |
|||
* b) a gzipped tarball containing (a) |
|||
* c) a url that resolves to (b) |
|||
* d) a `<name>@<version>` that is published on the registry with (c) |
|||
* e) a `<name>@<tag>` that points to (d) |
|||
* f) a `<name>` that has a "latest" tag satisfying (e) |
|||
* g) a `<git remote url>` that resolves to (b) |
|||
|
|||
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). |
|||
|
|||
|
|||
* `npm install` (in package directory, no arguments): |
|||
|
|||
Install the dependencies in the local node_modules folder. |
|||
|
|||
In global mode (ie, with `-g` or `--global` appended to the command), |
|||
it installs the current package context (ie, the current working |
|||
directory) as a global package. |
|||
|
|||
|
|||
* `npm install <folder>`: |
|||
|
|||
Install a package that is sitting in a folder on the filesystem. |
|||
|
|||
* `npm install <tarball file>`: |
|||
|
|||
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 `npm link`. |
|||
|
|||
Example: |
|||
|
|||
npm install ./package.tgz |
|||
|
|||
* `npm install <tarball url>`: |
|||
|
|||
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://" |
|||
|
|||
Example: |
|||
|
|||
npm install https://github.com/indexzero/forever/tarball/v0.5.6 |
|||
|
|||
* `npm install <name> [--save|--save-dev|--save-optional]`: |
|||
|
|||
Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See |
|||
`npm-config(7)`.) |
|||
|
|||
In most cases, this will install the latest version |
|||
of the module published on npm. |
|||
|
|||
Example: |
|||
|
|||
npm install sax |
|||
|
|||
`npm install` takes 3 exclusive, optional flags which save or update |
|||
the package version in your main package.json: |
|||
|
|||
* `--save`: Package will appear in your `dependencies`. |
|||
|
|||
* `--save-dev`: Package will appear in your `devDependencies`. |
|||
|
|||
* `--save-optional`: Package will appear in your `optionalDependencies`. |
|||
|
|||
Examples: |
|||
|
|||
npm install sax --save |
|||
npm install node-tap --save-dev |
|||
npm install dtrace-provider --save-optional |
|||
|
|||
|
|||
**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. |
|||
|
|||
* `npm install <name>@<tag>`: |
|||
|
|||
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. |
|||
|
|||
Example: |
|||
|
|||
npm install sax@latest |
|||
|
|||
* `npm install <name>@<version>`: |
|||
|
|||
Install the specified version of the package. This will fail if the version |
|||
has not been published to the registry. |
|||
|
|||
Example: |
|||
|
|||
npm install sax@0.1.1 |
|||
|
|||
* `npm install <name>@<version range>`: |
|||
|
|||
Install a version of the package matching the specified version range. This |
|||
will follow the same rules for resolving dependencies described in `package.json(5)`. |
|||
|
|||
Note that most version ranges must be put in quotes so that your shell will |
|||
treat it as a single argument. |
|||
|
|||
Example: |
|||
|
|||
npm install sax@">=0.1.0 <0.2.0" |
|||
|
|||
* `npm install <git remote url>`: |
|||
|
|||
Install a package by cloning a git remote url. The format of the git |
|||
url is: |
|||
|
|||
<protocol>://[<user>@]<hostname><separator><path>[#<commit-ish>] |
|||
|
|||
`<protocol>` is one of `git`, `git+ssh`, `git+http`, or |
|||
`git+https`. If no `<commit-ish>` is specified, then `master` is |
|||
used. |
|||
|
|||
Examples: |
|||
|
|||
git+ssh://git@github.com:isaacs/npm.git#v1.0.27 |
|||
git+https://isaacs@github.com/isaacs/npm.git |
|||
git://github.com/isaacs/npm.git#v1.0.27 |
|||
|
|||
You may combine multiple arguments, and even multiple types of arguments. |
|||
For example: |
|||
|
|||
npm install sax@">=0.1.0 <0.2.0" bench supervisor |
|||
|
|||
The `--tag` argument will apply to all of the specified install targets. |
|||
|
|||
The `--force` argument will force npm to fetch remote resources even if a |
|||
local copy exists on disk. |
|||
|
|||
npm install sax --force |
|||
|
|||
The `--global` argument will cause npm to install the package globally |
|||
rather than locally. See `npm-folders(7)`. |
|||
|
|||
The `--link` argument will cause npm to link global installs into the |
|||
local space in some cases. |
|||
|
|||
The `--no-bin-links` argument will prevent npm from creating symlinks for |
|||
any binaries the package might contain. |
|||
|
|||
The `--no-shrinkwrap` argument, which will ignore an available |
|||
shrinkwrap file and use the package.json instead. |
|||
|
|||
The `--nodedir=/path/to/node/source` argument will allow npm to find the |
|||
node source code so that npm can compile native modules. |
|||
|
|||
See `npm-config(7)`. Many of the configuration params have some |
|||
effect on installation, since that's most of what npm does. |
|||
|
|||
## ALGORITHM |
|||
|
|||
To install a package, npm uses the following algorithm: |
|||
|
|||
install(where, what, family, ancestors) |
|||
fetch what, unpack to <where>/node_modules/<what> |
|||
for each dep in what.dependencies |
|||
resolve dep to precise version |
|||
for each dep@version in what.dependencies |
|||
not in <where>/node_modules/<what>/node_modules/* |
|||
and not in <family> |
|||
add precise version deps to <family> |
|||
install(<where>/node_modules/<what>, dep, family) |
|||
|
|||
For this `package{dep}` structure: `A{B,C}, B{C}, C{D}`, |
|||
this algorithm produces: |
|||
|
|||
A |
|||
+-- B |
|||
`-- C |
|||
`-- D |
|||
|
|||
That is, the dependency from B to C is satisfied by the fact that A |
|||
already caused C to be installed at a higher level. |
|||
|
|||
See npm-folders(7) for a more detailed description of the specific |
|||
folder structures that npm creates. |
|||
|
|||
### Limitations of npm's Install Algorithm |
|||
|
|||
There are some very rare and pathological edge-cases where a cycle can |
|||
cause npm to try to install a never-ending tree of packages. Here is |
|||
the simplest case: |
|||
|
|||
A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ... |
|||
|
|||
where `A` is some version of a package, and `A'` is a different version |
|||
of the same package. Because `B` depends on a different version of `A` |
|||
than the one that is already in the tree, it must install a separate |
|||
copy. The same is true of `A'`, which must install `B'`. Because `B'` |
|||
depends on the original version of `A`, which has been overridden, the |
|||
cycle falls into infinite regress. |
|||
|
|||
To avoid this situation, npm flat-out refuses to install any |
|||
`name@version` that is already present anywhere in the tree of package |
|||
folder ancestors. A more correct, but more complex, solution would be |
|||
to symlink the existing version into the new location. If this ever |
|||
affects a real use-case, it will be investigated. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-folders(7) |
|||
* npm-update(1) |
|||
* npm-link(1) |
|||
* npm-rebuild(1) |
|||
* npm-scripts(7) |
|||
* npm-build(1) |
|||
* npm-config(1) |
|||
* npm-config(7) |
|||
* npmrc(5) |
|||
* npm-registry(7) |
|||
* npm-folders(7) |
|||
* npm-tag(1) |
|||
* npm-rm(1) |
|||
* npm-shrinkwrap(1) |
|||
@ -0,0 +1,62 @@ |
|||
npm-link(1) -- Symlink a package folder |
|||
======================================= |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm link (in package folder) |
|||
npm link <pkgname> |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Package linking is a two-step process. |
|||
|
|||
First, `npm link` in a package folder will create a globally-installed |
|||
symbolic link from `prefix/package-name` to the current folder. |
|||
|
|||
Next, in some other location, `npm link package-name` will create a |
|||
symlink from the local `node_modules` folder to the global symlink. |
|||
|
|||
Note that `package-name` is taken from `package.json` , |
|||
not from directory name. |
|||
|
|||
When creating tarballs for `npm publish`, the linked packages are |
|||
"snapshotted" to their current state by resolving the symbolic links. |
|||
|
|||
This is |
|||
handy for installing your own stuff, so that you can work on it and test it |
|||
iteratively without having to continually rebuild. |
|||
|
|||
For example: |
|||
|
|||
cd ~/projects/node-redis # go into the package directory |
|||
npm link # creates global link |
|||
cd ~/projects/node-bloggy # go into some other package directory. |
|||
npm link redis # link-install the package |
|||
|
|||
Now, any changes to ~/projects/node-redis will be reflected in |
|||
~/projects/node-bloggy/node_modules/redis/ |
|||
|
|||
You may also shortcut the two steps in one. For example, to do the |
|||
above use-case in a shorter way: |
|||
|
|||
cd ~/projects/node-bloggy # go into the dir of your main project |
|||
npm link ../node-redis # link the dir of your dependency |
|||
|
|||
The second line is the equivalent of doing: |
|||
|
|||
(cd ../node-redis; npm link) |
|||
npm link redis |
|||
|
|||
That is, it first creates a global link, and then links the global |
|||
installation target into your project's `node_modules` folder. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-developers(7) |
|||
* npm-faq(7) |
|||
* package.json(5) |
|||
* npm-install(1) |
|||
* npm-folders(7) |
|||
* npm-config(1) |
|||
* npm-config(7) |
|||
* npmrc(5) |
|||
@ -0,0 +1,74 @@ |
|||
npm-ls(1) -- List installed packages |
|||
====================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm list [<pkg> ...] |
|||
npm ls [<pkg> ...] |
|||
npm la [<pkg> ...] |
|||
npm ll [<pkg> ...] |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This command will print to stdout all the versions of packages that are |
|||
installed, as well as their dependencies, in a tree-structure. |
|||
|
|||
Positional arguments are `name@version-range` identifiers, which will |
|||
limit the results to only the paths to the packages named. Note that |
|||
nested packages will *also* show the paths to the specified packages. |
|||
For example, running `npm ls promzard` in npm's source tree will show: |
|||
|
|||
npm@@VERSION@ /path/to/npm |
|||
└─┬ init-package-json@0.0.4 |
|||
└── promzard@0.1.5 |
|||
|
|||
It will print out extraneous, missing, and invalid packages. |
|||
|
|||
If a project specifies git urls for dependencies these are shown |
|||
in parentheses after the name@version to make it easier for users to |
|||
recognize potential forks of a project. |
|||
|
|||
When run as `ll` or `la`, it shows extended information by default. |
|||
|
|||
## CONFIGURATION |
|||
|
|||
### json |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Show information in JSON format. |
|||
|
|||
### long |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Show extended information. |
|||
|
|||
### parseable |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
Show parseable output instead of tree view. |
|||
|
|||
### global |
|||
|
|||
* Default: false |
|||
* Type: Boolean |
|||
|
|||
List packages in the global install prefix instead of in the current |
|||
project. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-config(1) |
|||
* npm-config(7) |
|||
* npmrc(5) |
|||
* npm-folders(7) |
|||
* npm-install(1) |
|||
* npm-link(1) |
|||
* npm-prune(1) |
|||
* npm-outdated(1) |
|||
* npm-update(1) |
|||
@ -0,0 +1,17 @@ |
|||
npm-outdated(1) -- Check for outdated packages |
|||
============================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm outdated [<name> [<name> ...]] |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This command will check the registry to see if any (or, specific) installed |
|||
packages are currently outdated. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-update(1) |
|||
* npm-registry(7) |
|||
* npm-folders(7) |
|||
@ -0,0 +1,33 @@ |
|||
npm-owner(1) -- Manage package owners |
|||
===================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm owner ls <package name> |
|||
npm owner add <user> <package name> |
|||
npm owner rm <user> <package name> |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Manage ownership of published packages. |
|||
|
|||
* ls: |
|||
List all the users who have access to modify a package and push new versions. |
|||
Handy when you need to know who to bug for help. |
|||
* add: |
|||
Add a new user as a maintainer of a package. This user is enabled to modify |
|||
metadata, publish new versions, and add other owners. |
|||
* rm: |
|||
Remove a user from the package owner list. This immediately revokes their |
|||
privileges. |
|||
|
|||
Note that there is only one level of access. Either you can modify a package, |
|||
or you can't. Future versions may contain more fine-grained access levels, but |
|||
that is not implemented at this time. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-publish(1) |
|||
* npm-registry(7) |
|||
* npm-adduser(1) |
|||
* npm-disputes(7) |
|||
@ -0,0 +1,27 @@ |
|||
npm-pack(1) -- Create a tarball from a package |
|||
============================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm pack [<pkg> [<pkg> ...]] |
|||
|
|||
## DESCRIPTION |
|||
|
|||
For anything that's installable (that is, a package folder, tarball, |
|||
tarball url, name@tag, name@version, or name), this command will fetch |
|||
it to the cache, and then copy the tarball to the current working |
|||
directory as `<name>-<version>.tgz`, and then write the filenames out to |
|||
stdout. |
|||
|
|||
If the same package is specified multiple times, then the file will be |
|||
overwritten the second time. |
|||
|
|||
If no arguments are supplied, then npm packs the current package folder. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-cache(1) |
|||
* npm-publish(1) |
|||
* npm-config(1) |
|||
* npm-config(7) |
|||
* npmrc(5) |
|||
@ -0,0 +1,19 @@ |
|||
npm-prefix(1) -- Display prefix |
|||
=============================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm prefix |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Print the prefix to standard out. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-root(1) |
|||
* npm-bin(1) |
|||
* npm-folders(7) |
|||
* npm-config(1) |
|||
* npm-config(7) |
|||
* npmrc(5) |
|||
@ -0,0 +1,21 @@ |
|||
npm-prune(1) -- Remove extraneous packages |
|||
========================================== |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm prune [<name> [<name ...]] |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This command removes "extraneous" packages. If a package name is |
|||
provided, then only packages matching one of the supplied names are |
|||
removed. |
|||
|
|||
Extraneous packages are packages that are not listed on the parent |
|||
package's dependencies list. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-rm(1) |
|||
* npm-folders(7) |
|||
* npm-list(1) |
|||
@ -0,0 +1,30 @@ |
|||
npm-publish(1) -- Publish a package |
|||
=================================== |
|||
|
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm publish <tarball> |
|||
npm publish <folder> |
|||
|
|||
## DESCRIPTION |
|||
|
|||
Publishes a package to the registry so that it can be installed by name. |
|||
|
|||
* `<folder>`: |
|||
A folder containing a package.json file |
|||
|
|||
* `<tarball>`: |
|||
A url or file path to a gzipped tar archive containing a single folder |
|||
with a package.json file inside. |
|||
|
|||
Fails if the package name and version combination already exists in |
|||
the registry. Overwrites when the "--force" flag is set. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-registry(7) |
|||
* npm-adduser(1) |
|||
* npm-owner(1) |
|||
* npm-deprecate(1) |
|||
* npm-tag(1) |
|||
@ -0,0 +1,22 @@ |
|||
npm-restart(1) -- Start a package |
|||
================================= |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm restart <name> |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This runs a package's "restart" script, if one was provided. |
|||
Otherwise it runs package's "stop" script, if one was provided, and then |
|||
the "start" script. |
|||
|
|||
If no version is specified, then it restarts the "active" version. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-run-script(1) |
|||
* npm-scripts(7) |
|||
* npm-test(1) |
|||
* npm-start(1) |
|||
* npm-stop(1) |
|||
@ -0,0 +1,21 @@ |
|||
npm-rm(1) -- Remove a package |
|||
============================= |
|||
|
|||
## SYNOPSIS |
|||
|
|||
npm rm <name> |
|||
npm uninstall <name> |
|||
|
|||
## DESCRIPTION |
|||
|
|||
This uninstalls a package, completely removing everything npm installed |
|||
on its behalf. |
|||
|
|||
## SEE ALSO |
|||
|
|||
* npm-prune(1) |
|||
* npm-install(1) |
|||
* npm-folders(7) |
|||
* npm-config(1) |
|||
* npm-config(7) |
|||
* npmrc(5) |
|||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue