From 30818ab914736f8d2abbc8b45cff55fef2241ecc Mon Sep 17 00:00:00 2001 From: isaacs Date: Sat, 3 Sep 2011 22:34:02 -0700 Subject: html docs --- Makefile | 31 +- html/doc/adduser.html | 382 ++++++++++++++++++++ html/doc/author.html | 379 ++++++++++++++++++++ html/doc/bin.html | 363 +++++++++++++++++++ html/doc/build.html | 372 +++++++++++++++++++ html/doc/bundle.html | 363 +++++++++++++++++++ html/doc/cache.html | 407 +++++++++++++++++++++ html/doc/changelog.html | 377 ++++++++++++++++++++ html/doc/coding-style.html | 534 +++++++++++++++++++++++++++ html/doc/completion.html | 374 +++++++++++++++++++ html/doc/config.html | 871 +++++++++++++++++++++++++++++++++++++++++++++ html/doc/deprecate.html | 372 +++++++++++++++++++ html/doc/developers.html | 499 ++++++++++++++++++++++++++ html/doc/docs.html | 366 +++++++++++++++++++ html/doc/edit.html | 371 +++++++++++++++++++ html/doc/explore.html | 369 +++++++++++++++++++ html/doc/faq.html | 543 ++++++++++++++++++++++++++++ html/doc/find.html | 395 ++++++++++++++++++++ html/doc/folders.html | 534 +++++++++++++++++++++++++++ html/doc/get.html | 871 +++++++++++++++++++++++++++++++++++++++++++++ html/doc/global.html | 534 +++++++++++++++++++++++++++ html/doc/help-search.html | 381 ++++++++++++++++++++ html/doc/home.html | 366 +++++++++++++++++++ html/doc/index.html | 471 ++++++++++++++++++++++++ html/doc/init.html | 376 +++++++++++++++++++ html/doc/install.html | 426 ++++++++++++++++++++++ html/doc/json.html | 768 +++++++++++++++++++++++++++++++++++++++ html/doc/link.html | 401 +++++++++++++++++++++ html/doc/list.html | 395 ++++++++++++++++++++ html/doc/ln.html | 401 +++++++++++++++++++++ html/doc/ls.html | 395 ++++++++++++++++++++ html/doc/npm.html | 471 ++++++++++++++++++++++++ html/doc/outdated.html | 364 +++++++++++++++++++ html/doc/owner.html | 379 ++++++++++++++++++++ html/doc/pack.html | 372 +++++++++++++++++++ html/doc/prefix.html | 363 +++++++++++++++++++ html/doc/prune.html | 368 +++++++++++++++++++ html/doc/publish.html | 376 +++++++++++++++++++ html/doc/rebuild.html | 372 +++++++++++++++++++ html/doc/registry.html | 440 +++++++++++++++++++++++ html/doc/removing-npm.html | 394 ++++++++++++++++++++ html/doc/restart.html | 371 +++++++++++++++++++ html/doc/rm.html | 364 +++++++++++++++++++ html/doc/root.html | 363 +++++++++++++++++++ html/doc/run-script.html | 370 +++++++++++++++++++ html/doc/scripts.html | 508 ++++++++++++++++++++++++++ html/doc/search.html | 363 +++++++++++++++++++ html/doc/semver.html | 443 +++++++++++++++++++++++ html/doc/set.html | 871 +++++++++++++++++++++++++++++++++++++++++++++ html/doc/start.html | 363 +++++++++++++++++++ html/doc/stop.html | 363 +++++++++++++++++++ html/doc/submodule.html | 380 ++++++++++++++++++++ html/doc/tag.html | 364 +++++++++++++++++++ html/doc/test.html | 366 +++++++++++++++++++ html/doc/uninstall.html | 364 +++++++++++++++++++ html/doc/unpublish.html | 367 +++++++++++++++++++ html/doc/update.html | 366 +++++++++++++++++++ html/doc/version.html | 367 +++++++++++++++++++ html/doc/view.html | 431 ++++++++++++++++++++++ html/doc/whoami.html | 363 +++++++++++++++++++ html/docfoot.html | 30 ++ html/dochead.html | 324 +++++++++++++++++ 62 files changed, 25684 insertions(+), 3 deletions(-) create mode 100644 html/doc/adduser.html create mode 100644 html/doc/author.html create mode 100644 html/doc/bin.html create mode 100644 html/doc/build.html create mode 100644 html/doc/bundle.html create mode 100644 html/doc/cache.html create mode 100644 html/doc/changelog.html create mode 100644 html/doc/coding-style.html create mode 100644 html/doc/completion.html create mode 100644 html/doc/config.html create mode 100644 html/doc/deprecate.html create mode 100644 html/doc/developers.html create mode 100644 html/doc/docs.html create mode 100644 html/doc/edit.html create mode 100644 html/doc/explore.html create mode 100644 html/doc/faq.html create mode 100644 html/doc/find.html create mode 100644 html/doc/folders.html create mode 100644 html/doc/get.html create mode 100644 html/doc/global.html create mode 100644 html/doc/help-search.html create mode 100644 html/doc/home.html create mode 100644 html/doc/index.html create mode 100644 html/doc/init.html create mode 100644 html/doc/install.html create mode 100644 html/doc/json.html create mode 100644 html/doc/link.html create mode 100644 html/doc/list.html create mode 100644 html/doc/ln.html create mode 100644 html/doc/ls.html create mode 100644 html/doc/npm.html create mode 100644 html/doc/outdated.html create mode 100644 html/doc/owner.html create mode 100644 html/doc/pack.html create mode 100644 html/doc/prefix.html create mode 100644 html/doc/prune.html create mode 100644 html/doc/publish.html create mode 100644 html/doc/rebuild.html create mode 100644 html/doc/registry.html create mode 100644 html/doc/removing-npm.html create mode 100644 html/doc/restart.html create mode 100644 html/doc/rm.html create mode 100644 html/doc/root.html create mode 100644 html/doc/run-script.html create mode 100644 html/doc/scripts.html create mode 100644 html/doc/search.html create mode 100644 html/doc/semver.html create mode 100644 html/doc/set.html create mode 100644 html/doc/start.html create mode 100644 html/doc/stop.html create mode 100644 html/doc/submodule.html create mode 100644 html/doc/tag.html create mode 100644 html/doc/test.html create mode 100644 html/doc/uninstall.html create mode 100644 html/doc/unpublish.html create mode 100644 html/doc/update.html create mode 100644 html/doc/version.html create mode 100644 html/doc/view.html create mode 100644 html/doc/whoami.html create mode 100644 html/docfoot.html create mode 100644 html/dochead.html diff --git a/Makefile b/Makefile index bb2f8f475..3e90e4fea 100644 --- a/Makefile +++ b/Makefile @@ -4,6 +4,10 @@ docs = $(shell find doc -name '*.md' \ |sed 's|.md|.1|g' \ |sed 's|doc/|man1/|g' ) +htmldocs = $(shell find doc -name '*.md' \ + |sed 's|.md|.html|g' \ + |sed 's|doc/|html/doc/|g' ) html/doc/index.html + doc_subfolders = $(shell find doc -type d \ |sed 's|doc/|man1/|g' ) @@ -39,14 +43,35 @@ man: man1 man1: $(doc_subfolders) [ -d man1 ] || mkdir -p man1 -doc: man1 $(docs) +html/doc: $(doc_subfolders) + [ -d html/doc ] || mkdir -p html/doc + +doc: $(docs) $(htmldocs) # use `npm install ronn` for this to work. -man1/%.1: doc/%.md +man1/%.1: doc/%.md man1 @[ -x ./node_modules/.bin/ronn ] || node cli.js install ronn ./node_modules/.bin/ronn --roff $< > $@ -man1/%/: doc/%/ +man1/%/: doc/%/ man1 + @[ -d $@ ] || mkdir -p $@ + +# use `npm install ronn` for this to work. +html/doc/%.html: doc/%.md html/dochead.html html/docfoot.html html/doc + @[ -x ./node_modules/.bin/ronn ] || node cli.js install ronn + (cat html/dochead.html && \ + ./node_modules/.bin/ronn -f $< && \ + cat html/docfoot.html )\ + | sed 's|@NAME@|$*|g' \ + | sed 's|@DATE@|$(shell date -u +'%Y-%M-%d %H:%m:%S')|g' \ + | perl -pi -e 's/npm-([^\)]+)\(1\)/npm-\1(1)<\/a>/g' \ + | perl -pi -e 's/npm\(1\)/npm(1)<\/a>/g' \ + > $@ + +html/doc/index.html: html/doc/npm.html + cp $< $@ + +html/doc/%/: doc/%/ html/doc @[ -d $@ ] || mkdir -p $@ test: submodules diff --git a/html/doc/adduser.html b/html/doc/adduser.html new file mode 100644 index 000000000..69b53b375 --- /dev/null +++ b/html/doc/adduser.html @@ -0,0 +1,382 @@ + + + npm-adduser + + + +
+

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.

+
+ + + diff --git a/html/doc/author.html b/html/doc/author.html new file mode 100644 index 000000000..f77e98c3a --- /dev/null +++ b/html/doc/author.html @@ -0,0 +1,379 @@ + + + npm-author + + + +
+

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

+ + + +

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

+ + +
+ + + diff --git a/html/doc/bin.html b/html/doc/bin.html new file mode 100644 index 000000000..7a5c2f674 --- /dev/null +++ b/html/doc/bin.html @@ -0,0 +1,363 @@ + + + npm-bin + + + +
+

npm-bin(1) -- Display npm bin folder

+ +

SYNOPSIS

+ +
npm bin
+ +

DESCRIPTION

+ +

Print the folder where npm will install executables.

+
+ + + diff --git a/html/doc/build.html b/html/doc/build.html new file mode 100644 index 000000000..e8d8e6378 --- /dev/null +++ b/html/doc/build.html @@ -0,0 +1,372 @@ + + + npm-build + + + +
+

npm-build(1) -- Build a package

+ +

SYNOPSIS

+ +
npm build <package-folder>
+ + + +

DESCRIPTION

+ +

This is the plumbing command called by npm link and npm install.

+ +

It should generally not be called directly.

+ +

SEE ALSO

+ + +
+ + + diff --git a/html/doc/bundle.html b/html/doc/bundle.html new file mode 100644 index 000000000..50ef8b5d2 --- /dev/null +++ b/html/doc/bundle.html @@ -0,0 +1,363 @@ + + + npm-bundle + + + +
+

npm-bundle(1) -- REMOVED

+ +

DESCRIPTION

+ +

The npm bundle command has been removed in 1.0, for the simple reason +that it is no longer necessary, as the default behavior is now to +install packages into the local space.

+ +

Just use npm install now to do what npm bundle used to do.

+
+ + + diff --git a/html/doc/cache.html b/html/doc/cache.html new file mode 100644 index 000000000..34f1dc35c --- /dev/null +++ b/html/doc/cache.html @@ -0,0 +1,407 @@ + + + npm-cache + + + +
+

npm-cache(1) -- install a package

+ +

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

+ + + +

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}:

+ + + +

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.

+
+ + + diff --git a/html/doc/changelog.html b/html/doc/changelog.html new file mode 100644 index 000000000..25c70c02e --- /dev/null +++ b/html/doc/changelog.html @@ -0,0 +1,377 @@ + + + npm-changelog + + + +
+

npm-changelog(1) -- Changes

+ +

HISTORY

+ +

1.0

+ + + +

0.3

+ + + +

0.2

+ + + +

0.1

+ + + +

0.0

+ + +
+ + + diff --git a/html/doc/coding-style.html b/html/doc/coding-style.html new file mode 100644 index 000000000..1f8d2a7e5 --- /dev/null +++ b/html/doc/coding-style.html @@ -0,0 +1,534 @@ + + + npm-coding-style + + + +
+

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.

+ +

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:

+ + + +

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.

+ +

Use the require("./utils/log").er function. It takes a callback and an +error message, and returns an object that will report the message in the +event of a failure. It's quite handy.

+ +
function myThing (args, cb) {
+  getData(args, function (er, data) {
+    if (er) return log.er(cb, "Couldn't get data")(er)
+    doSomethingElse(data, cb)
+  })
+}
+function justHasToWork (cb) {
+  doSomething(log.er(cb, "the doSomething failed."))
+}
+ +

Logging

+ +

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. The default log() function logs at the +"info" level. See npm help config 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 CAPSSNAKECASE 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.

+
+ + + diff --git a/html/doc/completion.html b/html/doc/completion.html new file mode 100644 index 000000000..15c5c0234 --- /dev/null +++ b/html/doc/completion.html @@ -0,0 +1,374 @@ + + + npm-completion + + + +
+

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.

+
+ + + diff --git a/html/doc/config.html b/html/doc/config.html new file mode 100644 index 000000000..988f7f208 --- /dev/null +++ b/html/doc/config.html @@ -0,0 +1,871 @@ + + + npm-config + + + +
+

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 5 sources, in this priority:

+ + + +

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:

+ + + +

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 help scripts) +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

+ + + +

Force npm to always require authentication when accessing the registry, +even for GET requests.

+ +

bin-publish

+ + + +

If set to true, then binary packages will be created on publish.

+ +

This is the way to opt into the "bindist" behavior described below.

+ +

bindist

+ + + +

Experimental: on stable versions of node, binary distributions will be +created with this tag. If a user then installs that package, and their +bindist tag is found in the list of binary distributions, they will +get that prebuilt version.

+ +

Pre-build node packages have their preinstall, install, and postinstall +scripts stripped (since they are run prior to publishing), and do not +have their build directories automatically ignored.

+ +

It's yet to be seen if this is a good idea.

+ +

browser

+ + + +

The browser that is called by the npm docs command to open websites.

+ +

cache

+ + + +

The location of npm's cache directory. See npm help cache

+ +

color

+ + + +

If false, never shows colors. If "always" then always shows colors. +If true, then only prints color codes for tty file descriptors.

+ +

depth

+ + + +

The depth to go when recursing directories for npm ls and +npm cache ls.

+ +

description

+ + + +

Show the description in npm search

+ +

dev

+ + + +

Install dev-dependencies along with packages.

+ +

Note that dev-dependencies are also installed if the npat flag is +set.

+ +

editor

+ + + +

The command to run for npm edit or npm config edit.

+ +

force

+ + + +

Makes various commands more forceful.

+ + + +

global

+ + + +

Operates in "global" mode, so that packages are installed into the +prefix folder instead of the current working directory. See +npm help folders for more on the differences in behavior.

+ + + +

globalconfig

+ + + +

The config file to read for global config options.

+ +

globalignorefile

+ + + +

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

+ + + +

The group to use when running package scripts in global mode as the root +user.

+ +

gzipbin

+ + + +

The gzip binary

+ +

https-proxy

+ + + +

A proxy to use for outgoing https requests.

+ +

ignore

+ + + +

A white-space separated list of glob patterns of files to always exclude +from packages when building tarballs.

+ +

init.version

+ + + +

The value npm init should use by default for the package version.

+ +

init.author.name

+ + + +

The value npm init should use by default for the package author's name.

+ +

init.author.email

+ + + +

The value npm init should use by default for the package author's email.

+ +

init.author.url

+ + + +

The value npm init should use by default for the package author's homepage.

+ + + + + +

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:

+ + + +

logfd

+ + + +

The location to write log output.

+ +

loglevel

+ + + +

What level of logs to report. On failure, all logs are written to +npm-debug.log in the current working directory.

+ +

logprefix

+ + + +

Whether or not to prefix log messages with "npm" and the log level. See +also "color" and "loglevel".

+ +

long

+ + + +

Show extended information in npm ls

+ +

node-version

+ + + +

The node version to use when checking package's "engines" hash.

+ +

npat

+ + + +

Run tests on installation and report results to the +npaturl.

+ +

npaturl

+ + + +

The url to report npat test results.

+ +

onload-script

+ + + +

A node module to require() when npm loads. Useful for programmatic +usage.

+ +

outfd

+ + + +

Where to write "normal" output. This has no effect on log output.

+ +

parseable

+ + + +

Output parseable results from commands that write to +standard output.

+ +

prefix

+ + + +

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

+ + + +

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.
+ +

proxy

+ + + +

A proxy to use for outgoing http requests.

+ +

rebuild-bundle

+ + + +

Rebuild bundled dependencies after installation.

+ +

registry

+ + + +

The base URL of the npm package registry.

+ +

rollback

+ + + +

Remove failed installs.

+ +

save

+ + + +

Save installed packages to a package.json file as dependencies.

+ +

Only works if there is already a package.json file present.

+ +

searchopts

+ + + +

Space-separated options that are always passed to search.

+ +

searchexclude

+ + + +

Space-separated options that limit the results from search.

+ +

shell

+ + + +

The shell to run for the npm explore command.

+ +

tag

+ + + +

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.

+ +

tar

+ + + +

The tar executable

+ +

tmp

+ + + +

Where to store temporary files and folders. All temp files are deleted +on success, but left behind on failure for forensic purposes.

+ +

unicode

+ + + +

When set to true, npm uses unicode characters in the tree output. When +false, it uses ascii characters to draw trees.

+ +

unsafe-perm

+ + + +

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

+ + + +

Set to show short usage output (like the -H output) +instead of complete help when doing npm help.

+ +

user

+ + + +

The UID to set to when running package scripts as root.

+ +

username

+ + + +

The username on the npm registry. Set with npm adduser

+ +

userconfig

+ + + +

The location of user-level configuration settings.

+ +

userignorefile

+ + + +

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.

+ +

version

+ + + +

If true, output the npm version and exit successfully.

+ +

Only relevant when specified explicitly on the command line.

+ +

viewer

+ + + +

The program to use to view help content.

+ +

yes

+ + + +

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.

+
+ + + diff --git a/html/doc/deprecate.html b/html/doc/deprecate.html new file mode 100644 index 000000000..24abe187a --- /dev/null +++ b/html/doc/deprecate.html @@ -0,0 +1,372 @@ + + + npm-deprecate + + + +
+

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.

+
+ + + diff --git a/html/doc/developers.html b/html/doc/developers.html new file mode 100644 index 000000000..ee43db99c --- /dev/null +++ b/html/doc/developers.html @@ -0,0 +1,499 @@ + + + npm-developers + + + +
+

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.

+ +

Any time you see "see npm-whatever(1)", you can do man npm-whatever +or npm help whatever to get at the docs.

+ +

What is a `package`

+ +

A package is:

+ + + +

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).

+ +

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:

+ + + +

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.

+ + + +

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). So do this to get the +details:

+ +
npm help adduser
+ +

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 .npminclude +or .npmignore file to list out the globs to include/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!

+
+ + + diff --git a/html/doc/docs.html b/html/doc/docs.html new file mode 100644 index 000000000..42ea40b20 --- /dev/null +++ b/html/doc/docs.html @@ -0,0 +1,366 @@ + + + npm-docs + + + +
+

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.

+
+ + + diff --git a/html/doc/edit.html b/html/doc/edit.html new file mode 100644 index 000000000..b86c15cd7 --- /dev/null +++ b/html/doc/edit.html @@ -0,0 +1,371 @@ + + + npm-edit + + + +
+

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 help config.)

+ +

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.

+
+ + + diff --git a/html/doc/explore.html b/html/doc/explore.html new file mode 100644 index 000000000..41869a8b6 --- /dev/null +++ b/html/doc/explore.html @@ -0,0 +1,369 @@ + + + npm-explore + + + +
+

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.

+ +

Note that the package is not automatically rebuilt afterwards, so be +sure to use npm rebuild <pkg> if you make any changes.

+
+ + + diff --git a/html/doc/faq.html b/html/doc/faq.html new file mode 100644 index 000000000..1cf185064 --- /dev/null +++ b/html/doc/faq.html @@ -0,0 +1,543 @@ + + + npm-faq + + + +
+

npm-faq(1) -- Frequently Asked Questions

+ +

Where can I find these docs in HTML?

+ +

https://github.com/isaacs/npm/tree/master/doc

+ +

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 help folders

+ +

tl;dr:

+ + + +

How do I install something everywhere?

+ +

Install it globally by tacking -g or --global to the command.

+ +

I installed something globally, but I can't `require()` it

+ +

Install it locally.

+ +

I don't wanna.

+ +

Check out npm link. You might like it.

+ +

No, I really want 0.x style 'everything global' style.

+ +

Ok, fine. Do this:

+ +
echo 'export NODE_PATH="'$(npm root -g)'"' >> ~/.bashrc
+. ~/.bashrc
+npm config set global true
+ +

This is not recommended.

+ +

Many things will not work if you do this. Make sure you read and +understand npm help config and npm help global before you complain +about things being broken.

+ +

When you realize what a mistake it was, do this to switch back:

+ +
npm config delete global --local
+ +

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".

+ +

"NPM", however, is an acronym for the National Association of +Pastoral Musicians. You can learn more about them at http://npm.org/. +It is not an acronym, you see, but rather a capitonym.

+ +

In all earnestness, "npm" is named after its command-line utility, +which was mostly designed to be easily typed by right-handed programmers +using US QWERTY keyboard layouts, ending with the right-ring-finger in a +postition to type the "-" key for flags and other command-line +arguments, and 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 http://npmjs.org/install.sh | sh
+ +

What is a `package`?

+ +

A package is:

+ + + +

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:

+ + + +

How can I use npm for development?

+ +

See npm help developers and npm help json.

+ +

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 help registry.

+ +

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.)

+ + + +

See npm help link

+ +

The package registry website. What is that exactly?

+ +

See npm help registry.

+ +

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 http://admin.npmjs.org/reset.

+ +

I get ECONNREFUSED a lot. What's up?

+ +

Either the registry is down, or node's DNS isn't able to reach out. +This happens a lot if you don't follow all the steps in the Cygwin +setup doc.

+ +

To check if the registry is down, open up +http://registry.npmjs.org/-/short +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.

+ +

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.

+ + + +

Why does npm hate me?

+ +

npm is not capable of hatred. It loves everyone, especially you.

+
+ + + diff --git a/html/doc/find.html b/html/doc/find.html new file mode 100644 index 000000000..2f3161006 --- /dev/null +++ b/html/doc/find.html @@ -0,0 +1,395 @@ + + + npm-find + + + +
+

npm-ls(1) -- List installed packages

+ +

SYNOPSIS

+ +
npm list
+npm ls
+npm la
+npm ll
+ +

DESCRIPTION

+ +

This command will print to stdout all the versions of packages that are +installed, as well as their dependencies, in a tree-structure.

+ +

It does not take positional arguments, though you may set config flags +like with any other command, such as -g to list global packages.

+ +

It will print out extraneous, missing, and invalid packages.

+ +

When run as ll or la, it shows extended information by default.

+ +

CONFIGURATION

+ +

long

+ + + +

Show extended information.

+ +

parseable

+ + + +

Show parseable output instead of tree view.

+ +

global

+ + + +

List packages in the global install prefix instead of in the current +project.

+
+ + + diff --git a/html/doc/folders.html b/html/doc/folders.html new file mode 100644 index 000000000..02408e3b8 --- /dev/null +++ b/html/doc/folders.html @@ -0,0 +1,534 @@ + + + npm-folders + + + +
+

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

+ + + +

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.

+ +

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.

+ +

If you wish to require() a package, then install it locally.

+ +

Executables

+ +

When in global mode, executables are linked into prefix/bin.

+ +

When in local mode, executables are linked into +prefix/node_modules/.bin.

+ +

Man Pages

+ +

When in global mode, man pages are linked into prefix/share/man.

+ +

When in local mode, man pages are not installed.

+ +

Cache

+ +

See npm help cache. 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 either the TMPDIR environment +variable, or /tmp.

+ +

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 doing local installings, 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 cded +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 the module root is /usr/local/lib/node_modules, and bin files are +linked to /usr/local/bin instead of ./node_modules/.bin.

+ +

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 help json for more information.

+
+ + + diff --git a/html/doc/get.html b/html/doc/get.html new file mode 100644 index 000000000..d9c15ac69 --- /dev/null +++ b/html/doc/get.html @@ -0,0 +1,871 @@ + + + npm-get + + + +
+

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 5 sources, in this priority:

+ + + +

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:

+ + + +

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 help scripts) +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

+ + + +

Force npm to always require authentication when accessing the registry, +even for GET requests.

+ +

bin-publish

+ + + +

If set to true, then binary packages will be created on publish.

+ +

This is the way to opt into the "bindist" behavior described below.

+ +

bindist

+ + + +

Experimental: on stable versions of node, binary distributions will be +created with this tag. If a user then installs that package, and their +bindist tag is found in the list of binary distributions, they will +get that prebuilt version.

+ +

Pre-build node packages have their preinstall, install, and postinstall +scripts stripped (since they are run prior to publishing), and do not +have their build directories automatically ignored.

+ +

It's yet to be seen if this is a good idea.

+ +

browser

+ + + +

The browser that is called by the npm docs command to open websites.

+ +

cache

+ + + +

The location of npm's cache directory. See npm help cache

+ +

color

+ + + +

If false, never shows colors. If "always" then always shows colors. +If true, then only prints color codes for tty file descriptors.

+ +

depth

+ + + +

The depth to go when recursing directories for npm ls and +npm cache ls.

+ +

description

+ + + +

Show the description in npm search

+ +

dev

+ + + +

Install dev-dependencies along with packages.

+ +

Note that dev-dependencies are also installed if the npat flag is +set.

+ +

editor

+ + + +

The command to run for npm edit or npm config edit.

+ +

force

+ + + +

Makes various commands more forceful.

+ + + +

global

+ + + +

Operates in "global" mode, so that packages are installed into the +prefix folder instead of the current working directory. See +npm help folders for more on the differences in behavior.

+ + + +

globalconfig

+ + + +

The config file to read for global config options.

+ +

globalignorefile

+ + + +

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

+ + + +

The group to use when running package scripts in global mode as the root +user.

+ +

gzipbin

+ + + +

The gzip binary

+ +

https-proxy

+ + + +

A proxy to use for outgoing https requests.

+ +

ignore

+ + + +

A white-space separated list of glob patterns of files to always exclude +from packages when building tarballs.

+ +

init.version

+ + + +

The value npm init should use by default for the package version.

+ +

init.author.name

+ + + +

The value npm init should use by default for the package author's name.

+ +

init.author.email

+ + + +

The value npm init should use by default for the package author's email.

+ +

init.author.url

+ + + +

The value npm init should use by default for the package author's homepage.

+ + + + + +

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:

+ + + +

logfd

+ + + +

The location to write log output.

+ +

loglevel

+ + + +

What level of logs to report. On failure, all logs are written to +npm-debug.log in the current working directory.

+ +

logprefix

+ + + +

Whether or not to prefix log messages with "npm" and the log level. See +also "color" and "loglevel".

+ +

long

+ + + +

Show extended information in npm ls

+ +

node-version

+ + + +

The node version to use when checking package's "engines" hash.

+ +

npat

+ + + +

Run tests on installation and report results to the +npaturl.

+ +

npaturl

+ + + +

The url to report npat test results.

+ +

onload-script

+ + + +

A node module to require() when npm loads. Useful for programmatic +usage.

+ +

outfd

+ + + +

Where to write "normal" output. This has no effect on log output.

+ +

parseable

+ + + +

Output parseable results from commands that write to +standard output.

+ +

prefix

+ + + +

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

+ + + +

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.
+ +

proxy

+ + + +

A proxy to use for outgoing http requests.

+ +

rebuild-bundle

+ + + +

Rebuild bundled dependencies after installation.

+ +

registry

+ + + +

The base URL of the npm package registry.

+ +

rollback

+ + + +

Remove failed installs.

+ +

save

+ + + +

Save installed packages to a package.json file as dependencies.

+ +

Only works if there is already a package.json file present.

+ +

searchopts

+ + + +

Space-separated options that are always passed to search.

+ +

searchexclude

+ + + +

Space-separated options that limit the results from search.

+ +

shell

+ + + +

The shell to run for the npm explore command.

+ +

tag

+ + + +

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.

+ +

tar

+ + + +

The tar executable

+ +

tmp

+ + + +

Where to store temporary files and folders. All temp files are deleted +on success, but left behind on failure for forensic purposes.

+ +

unicode

+ + + +

When set to true, npm uses unicode characters in the tree output. When +false, it uses ascii characters to draw trees.

+ +

unsafe-perm

+ + + +

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

+ + + +

Set to show short usage output (like the -H output) +instead of complete help when doing npm help.

+ +

user

+ + + +

The UID to set to when running package scripts as root.

+ +

username

+ + + +

The username on the npm registry. Set with npm adduser

+ +

userconfig

+ + + +

The location of user-level configuration settings.

+ +

userignorefile

+ + + +

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.

+ +

version

+ + + +

If true, output the npm version and exit successfully.

+ +

Only relevant when specified explicitly on the command line.

+ +

viewer

+ + + +

The program to use to view help content.

+ +

yes

+ + + +

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.

+
+ + + diff --git a/html/doc/global.html b/html/doc/global.html new file mode 100644 index 000000000..6515088e3 --- /dev/null +++ b/html/doc/global.html @@ -0,0 +1,534 @@ + + + npm-global + + + +
+

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

+ + + +

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.

+ +

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.

+ +

If you wish to require() a package, then install it locally.

+ +

Executables

+ +

When in global mode, executables are linked into prefix/bin.

+ +

When in local mode, executables are linked into +prefix/node_modules/.bin.

+ +

Man Pages

+ +

When in global mode, man pages are linked into prefix/share/man.

+ +

When in local mode, man pages are not installed.

+ +

Cache

+ +

See npm help cache. 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 either the TMPDIR environment +variable, or /tmp.

+ +

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 doing local installings, 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 cded +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 the module root is /usr/local/lib/node_modules, and bin files are +linked to /usr/local/bin instead of ./node_modules/.bin.

+ +

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 help json for more information.

+
+ + + diff --git a/html/doc/help-search.html b/html/doc/help-search.html new file mode 100644 index 000000000..2d6b7a7a2 --- /dev/null +++ b/html/doc/help-search.html @@ -0,0 +1,381 @@ + + + npm-help-search + + + +
+

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

+ + + +

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.

+
+ + + diff --git a/html/doc/home.html b/html/doc/home.html new file mode 100644 index 000000000..ec24fc372 --- /dev/null +++ b/html/doc/home.html @@ -0,0 +1,366 @@ + + + npm-home + + + +
+

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.

+
+ + + diff --git a/html/doc/index.html b/html/doc/index.html new file mode 100644 index 000000000..d094bfbf2 --- /dev/null +++ b/html/doc/index.html @@ -0,0 +1,471 @@ + + + npm-npm + + + +
+

npm(1) -- node package manager

+ +

SYNOPSIS

+ +
npm <command> [args]
+ +

DESCRIPTION

+ +

npm is the package manager for the Node JavaScript platform. It puts +modules in place so that node can find them, and manages dependency +conflicts intelligently.

+ +

It is extremely configurable to support a wide variety of use cases. +Most commonly, it is used to publish, discover, install, and develop node +programs.

+ +

Run npm help to get a list of available commands.

+ +

INTRODUCTION

+ +

You probably got npm because you want to install stuff.

+ +

Use npm install blerg to install the latest version of "blerg". Check out +npm help install for more info. It can do a lot of stuff.

+ +

Use the npm search command to show everything that's available. +Use npm ls to show everything you've installed.

+ +

DIRECTORIES

+ +

See npm help folders to learn about where npm puts stuff.

+ +

In particular, npm has two modes of operation:

+ + + +

Local mode is the default. Use --global or -g on any command to +operate in global mode instead.

+ +

DEVELOPER USAGE

+ +

If you're using npm to develop and publish your code, check out the +following help topics:

+ + + +

CONFIGURATION

+ +

npm is extremely configurable. It reads its configuration options from +5 places.

+ + + +

See npm help config for much much more information.

+ +

CONTRIBUTIONS

+ +

Patches welcome!

+ + + +

Contributors are listed in npm's package.json file. You can view them +easily by doing npm view npm contributors.

+ +

If you would like to contribute, but don't know what to work on, check +the issues list or ask on the mailing list.

+ + + +

BUGS

+ +

When you find issues, please report them:

+ + + +

Be sure to include all of the output from the npm command that didn't work +as expected. The npm-debug.log file is also helpful to provide.

+ +

You can also look for isaacs in #node.js on irc://irc.freenode.net. He +will no doubt tell you to put the output in a gist or email.

+ +

HISTORY

+ +

See npm-changelog(1)

+ +

AUTHOR

+ +

Isaac Z. Schlueter :: isaacs :: @izs :: i@izs.me

+
+ + + diff --git a/html/doc/init.html b/html/doc/init.html new file mode 100644 index 000000000..505c70a71 --- /dev/null +++ b/html/doc/init.html @@ -0,0 +1,376 @@ + + + npm-init + + + +
+

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

+ +

npm-json(1)

+
+ + + diff --git a/html/doc/install.html b/html/doc/install.html new file mode 100644 index 000000000..588194368 --- /dev/null +++ b/html/doc/install.html @@ -0,0 +1,426 @@ + + + npm-install + + + +
+

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>
+npm install <name>@<tag>
+npm install <name>@<version>
+npm install <name>@<version range>
+ +

DESCRIPTION

+ +

This command installs a package, and any packages that it depends on.

+ +

A package is:

+ + + +

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).

+ + + +

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 help global.

+ +

The --link argument will cause npm to link global installs into the +local space in some cases.

+ +

See npm help config. Many of the configuration params have some +effect on installation, since that's most of what npm does.

+ +

SEE ALSO

+ + +
+ + + diff --git a/html/doc/json.html b/html/doc/json.html new file mode 100644 index 000000000..6d5651856 --- /dev/null +++ b/html/doc/json.html @@ -0,0 +1,768 @@ + + + npm-json + + + +
+

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 help config.

+ +

DEFAULT VALUES

+ +

npm will default some values based on package contents.

+ + + +

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:

+ + + +

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, 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:

+ + + +

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.

+ +

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 link that file into +place right next to wherever node is installed. (Presumably, this is in your +PATH, and defaults to /usr/local/bin.) On activation, the versioned file +will get linked to the main filename (just like how the main.js stuff works, +but with an executable in the PATH.)

+ +

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-version. Then, when you activate that version, it'll +create a symlink from /usr/local/bin/npm-version to /usr/local/bin/npm.

+ +

Notice that if the executable file is interpreted by node (i.e., specifying +node in the shebang line), npm actually installs a shim instead of symlinking +it, which causes expressions require.main === module and module.id === "." +evaluate to false within the file. This seems unable to be resolved until +node provides a "flexible require()".

+ +

Shortcut: If you have a single executable, and its name is already what you +want it to be, then you can just supply it as a string. For example:

+ +
{ "bin" : "./path/to/program" }
+ +

would be the same as this:

+ +
{ "bin" : { "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 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, +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 help scripts 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 help config and npm help scripts 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.

+ + + +

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.

+ + + +

For example, the following are equivalent:

+ + + +

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:

+ + + +

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.

+ +

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, and can +be managed like any other npm configuration param. See npm help +config for more on the topic.

+ +

bundledDependencies

+ +

Array of package names that will be bundled when publishing the package.

+ +

engines

+ +

Packages/1.0 says that you can have an "engines" field with an array of engine +names. However, it has no provision for specifying which version of the engine +your stuff runs on.

+ +

With npm, you can use either of the following styles to specify the version of +node that your stuff works on:

+ +
{ "engines" : [ "node >=0.1.27 <0.1.30" ] }
+ +

or:

+ +
{ "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.

+ +

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 speciic 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 help config to see the list of config options that can be +overridden.

+
+ + + diff --git a/html/doc/link.html b/html/doc/link.html new file mode 100644 index 000000000..a98c23109 --- /dev/null +++ b/html/doc/link.html @@ -0,0 +1,401 @@ + + + npm-link + + + +
+

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.

+ +

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.

+
+ + + diff --git a/html/doc/list.html b/html/doc/list.html new file mode 100644 index 000000000..c7ab746b4 --- /dev/null +++ b/html/doc/list.html @@ -0,0 +1,395 @@ + + + npm-list + + + +
+

npm-ls(1) -- List installed packages

+ +

SYNOPSIS

+ +
npm list
+npm ls
+npm la
+npm ll
+ +

DESCRIPTION

+ +

This command will print to stdout all the versions of packages that are +installed, as well as their dependencies, in a tree-structure.

+ +

It does not take positional arguments, though you may set config flags +like with any other command, such as -g to list global packages.

+ +

It will print out extraneous, missing, and invalid packages.

+ +

When run as ll or la, it shows extended information by default.

+ +

CONFIGURATION

+ +

long

+ + + +

Show extended information.

+ +

parseable

+ + + +

Show parseable output instead of tree view.

+ +

global

+ + + +

List packages in the global install prefix instead of in the current +project.

+
+ + + diff --git a/html/doc/ln.html b/html/doc/ln.html new file mode 100644 index 000000000..3d122b932 --- /dev/null +++ b/html/doc/ln.html @@ -0,0 +1,401 @@ + + + npm-ln + + + +
+

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.

+ +

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.

+
+ + + diff --git a/html/doc/ls.html b/html/doc/ls.html new file mode 100644 index 000000000..06d2ddfac --- /dev/null +++ b/html/doc/ls.html @@ -0,0 +1,395 @@ + + + npm-ls + + + +
+

npm-ls(1) -- List installed packages

+ +

SYNOPSIS

+ +
npm list
+npm ls
+npm la
+npm ll
+ +

DESCRIPTION

+ +

This command will print to stdout all the versions of packages that are +installed, as well as their dependencies, in a tree-structure.

+ +

It does not take positional arguments, though you may set config flags +like with any other command, such as -g to list global packages.

+ +

It will print out extraneous, missing, and invalid packages.

+ +

When run as ll or la, it shows extended information by default.

+ +

CONFIGURATION

+ +

long

+ + + +

Show extended information.

+ +

parseable

+ + + +

Show parseable output instead of tree view.

+ +

global

+ + + +

List packages in the global install prefix instead of in the current +project.

+
+ + + diff --git a/html/doc/npm.html b/html/doc/npm.html new file mode 100644 index 000000000..d094bfbf2 --- /dev/null +++ b/html/doc/npm.html @@ -0,0 +1,471 @@ + + + npm-npm + + + +
+

npm(1) -- node package manager

+ +

SYNOPSIS

+ +
npm <command> [args]
+ +

DESCRIPTION

+ +

npm is the package manager for the Node JavaScript platform. It puts +modules in place so that node can find them, and manages dependency +conflicts intelligently.

+ +

It is extremely configurable to support a wide variety of use cases. +Most commonly, it is used to publish, discover, install, and develop node +programs.

+ +

Run npm help to get a list of available commands.

+ +

INTRODUCTION

+ +

You probably got npm because you want to install stuff.

+ +

Use npm install blerg to install the latest version of "blerg". Check out +npm help install for more info. It can do a lot of stuff.

+ +

Use the npm search command to show everything that's available. +Use npm ls to show everything you've installed.

+ +

DIRECTORIES

+ +

See npm help folders to learn about where npm puts stuff.

+ +

In particular, npm has two modes of operation:

+ + + +

Local mode is the default. Use --global or -g on any command to +operate in global mode instead.

+ +

DEVELOPER USAGE

+ +

If you're using npm to develop and publish your code, check out the +following help topics:

+ + + +

CONFIGURATION

+ +

npm is extremely configurable. It reads its configuration options from +5 places.

+ + + +

See npm help config for much much more information.

+ +

CONTRIBUTIONS

+ +

Patches welcome!

+ + + +

Contributors are listed in npm's package.json file. You can view them +easily by doing npm view npm contributors.

+ +

If you would like to contribute, but don't know what to work on, check +the issues list or ask on the mailing list.

+ + + +

BUGS

+ +

When you find issues, please report them:

+ + + +

Be sure to include all of the output from the npm command that didn't work +as expected. The npm-debug.log file is also helpful to provide.

+ +

You can also look for isaacs in #node.js on irc://irc.freenode.net. He +will no doubt tell you to put the output in a gist or email.

+ +

HISTORY

+ +

See npm-changelog(1)

+ +

AUTHOR

+ +

Isaac Z. Schlueter :: isaacs :: @izs :: i@izs.me

+
+ + + diff --git a/html/doc/outdated.html b/html/doc/outdated.html new file mode 100644 index 000000000..f9c7e1671 --- /dev/null +++ b/html/doc/outdated.html @@ -0,0 +1,364 @@ + + + npm-outdated + + + +
+

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.

+
+ + + diff --git a/html/doc/owner.html b/html/doc/owner.html new file mode 100644 index 000000000..308f647a4 --- /dev/null +++ b/html/doc/owner.html @@ -0,0 +1,379 @@ + + + npm-owner + + + +
+

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

+ + + +

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

+ + +
+ + + diff --git a/html/doc/pack.html b/html/doc/pack.html new file mode 100644 index 000000000..d435fce39 --- /dev/null +++ b/html/doc/pack.html @@ -0,0 +1,372 @@ + + + npm-pack + + + +
+

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.

+
+ + + diff --git a/html/doc/prefix.html b/html/doc/prefix.html new file mode 100644 index 000000000..4306757e5 --- /dev/null +++ b/html/doc/prefix.html @@ -0,0 +1,363 @@ + + + npm-prefix + + + +
+

npm-prefix(1) -- Display prefix

+ +

SYNOPSIS

+ +
npm prefix
+ +

DESCRIPTION

+ +

Print the prefix to standard out.

+
+ + + diff --git a/html/doc/prune.html b/html/doc/prune.html new file mode 100644 index 000000000..4cdeb3767 --- /dev/null +++ b/html/doc/prune.html @@ -0,0 +1,368 @@ + + + npm-prune + + + +
+

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.

+
+ + + diff --git a/html/doc/publish.html b/html/doc/publish.html new file mode 100644 index 000000000..a75dc28a2 --- /dev/null +++ b/html/doc/publish.html @@ -0,0 +1,376 @@ + + + npm-publish + + + +
+

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.

+ + + +

Fails if the package name and version combination already exists in +the registry. Overwrites when the "--force" flag is set.

+ +

SEE ALSO

+ + +
+ + + diff --git a/html/doc/rebuild.html b/html/doc/rebuild.html new file mode 100644 index 000000000..e3d151efb --- /dev/null +++ b/html/doc/rebuild.html @@ -0,0 +1,372 @@ + + + npm-rebuild + + + +
+

npm-rebuild(1) -- Rebuild a package

+ +

SYNOPSIS

+ +
npm rebuild [<name> [<name> ...]]
+ + + +

DESCRIPTION

+ +

This command runs the npm build command on the matched folders. This is useful +when you install a new version of node, and must recompile all your C++ addons with +the new binary.

+ +

CONFIGURATION

+ +

See npm help build

+
+ + + diff --git a/html/doc/registry.html b/html/doc/registry.html new file mode 100644 index 000000000..cff0afa85 --- /dev/null +++ b/html/doc/registry.html @@ -0,0 +1,440 @@ + + + npm-registry + + + +
+

npm-registry(1) -- The JavaScript Package Registry

+ +

DESCRIPTION

+ +

To resolve packages by name and version, npm talks to a registry website +that implements the CommonJS Package Registry specification for reading +package info.

+ +

Additionally, npm's package registry implementation supports several +write APIs as well, to allow for publishing packages and managing user +account information.

+ +

The official public npm registry is at http://registry.npmjs.org/. It +is powered by a CouchDB database at +http://isaacs.couchone.com/registry. The code for the couchapp is +available at http://github.com/isaacs/npmjs.org. npm user accounts +are CouchDB users, stored in the http://isaacs.couchone.com/_users +database.

+ +

The registry URL is supplied by the registry config parameter. See +npm help config for more on managing npm's configuration.

+ +

Can I run my own private registry?

+ +

Yes!

+ +

The easiest way is to replicate the couch database, and use the same (or +similar) design doc to implement the APIs.

+ +

If you set up continuous replication from the official CouchDB, and then +set your internal CouchDB as the registry config, then you'll be able +to read any published packages, in addition to your private ones, and by +default will only publish internally. If you then want to publish a +package for the whole world to see, you can simply override the +--registry config for that command.

+ +

I don't want my package published in the official registry. It's private.

+ +

Set "private": true in your package.json to prevent it from being +published at all, or +"publishConfig":{"registry":"http://my-internal-registry.local"} +to force it to be published only to your internal registry.

+ +

See npm help json for more info on what goes in the package.json file.

+ +

Will you replicate from my registry into the public one?

+ +

No. If you want things to be public, then publish them into the public +registry using npm. What little security there is would be for nought +otherwise.

+ +

Do I have to use couchdb to build a registry that npm can talk to?

+ +

No, but it's way easier.

+ +

I published something elsewhere, and want to tell the npm registry about it.

+ +

That is supported, but not using the npm client. You'll have to get +your hands dirty and do some HTTP. The request looks something like +this:

+ +
PUT /my-foreign-package
+content-type:application/json
+accept:application/json
+authorization:Basic $base_64_encoded
+
+{ "name":"my-foreign-package"
+, "maintainers":["owner","usernames"]
+, "description":"A package that is hosted elsewhere"
+, "keywords":["nih","my cheese smells the best"]
+, "url":"http://my-different-registry.com/blerg/my-local-package"
+}
+ +

(Keywords and description are optional, but recommended. Name, +maintainers, and url are required.)

+ +

Then, when a user tries to install "my-foreign-package", it'll redirect +to your registry. If that doesn't resolve to a valid package entry, +then it'll fail, so please make sure that you understand the spec, and +ask for help on the npm-@googlegroups.com mailing list.

+ +

Is there a website or something to see package docs and such?

+ +

No, but such a thing is planned, and a tiny bit developed.

+ +

Stay tuned!

+
+ + + diff --git a/html/doc/removing-npm.html b/html/doc/removing-npm.html new file mode 100644 index 000000000..64442a410 --- /dev/null +++ b/html/doc/removing-npm.html @@ -0,0 +1,394 @@ + + + npm-removing-npm + + + +
+

npm-removal(1) -- Cleaning the Slate

+ +

SUMMARY

+ +

So sad to see you go.

+ +
sudo npm uninstall npm -g
+ +

Or, if that fails, get the npm source code, and do:

+ +
sudo make uninstall
+ +

More Severe Uninstalling

+ +

Usually, the above instructions are sufficient. That will remove +npm, but leave behind anything you've installed.

+ +

If that doesn't work, or if you require more drastic measures, +continue reading.

+ +

This assumes that you installed node and npm in the default place. If +you configured node with a different --prefix, or installed npm with a +different prefix setting, then adjust the paths accordingly, replacing +/usr/local with your install prefix.

+ +

rm -rf /usr/local/{lib/node,lib/node/.npm,bin,share/man}/npm*

+ +

If you installed things with npm, then your best bet is to uninstall +them with npm first, and then install them again once you have a +proper install. This can help find any symlinks that are lying +around:

+ +

ls -laF /usr/local/{lib/node,lib/node/.npm,bin,share/man} | grep npm

+ +

Prior to version 0.3, npm used shim files for executables and node +modules. To track those down, you can do the following:

+ +

find /usr/local/{lib/node,bin} -exec grep -l npm {} \; ;

+ +

(This is also in the README file.)

+
+ + + diff --git a/html/doc/restart.html b/html/doc/restart.html new file mode 100644 index 000000000..5a029cc34 --- /dev/null +++ b/html/doc/restart.html @@ -0,0 +1,371 @@ + + + npm-restart + + + +
+

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

+ + +
+ + + diff --git a/html/doc/rm.html b/html/doc/rm.html new file mode 100644 index 000000000..f9b229dac --- /dev/null +++ b/html/doc/rm.html @@ -0,0 +1,364 @@ + + + npm-rm + + + +
+

npm-uninstall(1) -- Remove a package

+ +

SYNOPSIS

+ +
npm uninstall <name>
+npm rm <name>
+ +

DESCRIPTION

+ +

This uninstalls a package, completely removing everything installed for it.

+
+ + + diff --git a/html/doc/root.html b/html/doc/root.html new file mode 100644 index 000000000..dd595a449 --- /dev/null +++ b/html/doc/root.html @@ -0,0 +1,363 @@ + + + npm-root + + + +
+

npm-root(1) -- Display npm root

+ +

SYNOPSIS

+ +
npm root
+ +

DESCRIPTION

+ +

Print the effective node_modules folder to standard out.

+
+ + + diff --git a/html/doc/run-script.html b/html/doc/run-script.html new file mode 100644 index 000000000..a0dc6f57a --- /dev/null +++ b/html/doc/run-script.html @@ -0,0 +1,370 @@ + + + npm-run-script + + + +
+

npm-run-script(1) -- Run arbitrary package scripts

+ +

SYNOPSIS

+ +
npm run-script <script> <name>
+ +

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.

+ +

SEE ALSO

+ + +
+ + + diff --git a/html/doc/scripts.html b/html/doc/scripts.html new file mode 100644 index 000000000..3130f7346 --- /dev/null +++ b/html/doc/scripts.html @@ -0,0 +1,508 @@ + + + npm-scripts + + + +
+

npm-scripts(1) -- How npm handles the "scripts" field

+ +

DESCRIPTION

+ +

npm supports the "scripts" member of the package.json script, for the +following scripts:

+ + + +

Additionally, arbitrary scrips can be run by doing +npm run-script <stage> <pkg>.

+ +

DEFAULT VALUES

+ +

npm will default some script values based on package contents.

+ + + +

USER

+ +

If npm was invoked with root privileges, then it will change the uid to +the user account or uid specified by the user config, which defaults +to nobody. Set the unsafe-perm flag to run scripts with root +privileges.

+ +

ENVIRONMENT

+ +

Package scripts run in an environment where many pieces of information are +made available regarding the setup of npm and the current state of the +process.

+ +

package.json vars

+ +

The package.json fields are tacked onto the npm_package_ prefix. So, for +instance, if you had {"name":"foo", "version":"1.2.5"} in your package.json +file, then your package scripts would have the npm_package_name environment +variable set to "foo", and the npm_package_version set to "1.2.5"

+ +

configuration

+ +

Configuration parameters are put in the environment with the npm_config_ +prefix. For instance, you can view the effective root config by checking the +npm_config_root environment variable.

+ +

Special: package.json "config" hash

+ +

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
+ +

current lifecycle event

+ +

Lastly, the npm_lifecycle_event environment variable is set to whichever +stage of the cycle is being executed. So, you could have a single script used +for different parts of the process which switches based on what's currently +happening.

+ +

Objects are flattened following this format, so if you had +{"scripts":{"install":"foo.js"}} in your package.json, then you'd see this +in the script:

+ +
process.env.npm_package_scripts_install === "foo.js"
+ +

EXAMPLES

+ +

For example, if your package.json contains this:

+ +
{ "scripts" :
+  { "install" : "scripts/install.js"
+  , "postinstall" : "scripts/install.js"
+  , "activate" : "scripts/install.js"
+  , "uninstall" : "scripts/uninstall.js"
+  }
+}
+ +

then the scripts/install.js will be called for the install, post-install, +and activate stages of the lifecycle, and the scripts/uninstall.js would be +called when the package is uninstalled. Since scripts/install.js is running +for three different phases, it would be wise in this case to look at the +npm_lifecycle_event environment variable.

+ +

If you want to run a make command, you can do so. This works just fine:

+ +
{ "scripts" :
+  { "preinstall" : "./configure"
+  , "install" : "make && make install"
+  , "test" : "make test"
+  }
+}
+ +

EXITING

+ +

Scripts are run by passing the line as a script argument to sh.

+ +

If the script exits with a code other than 0, then this will abort the +process.

+ +

Note that these script files don't have to be nodejs or even javascript +programs. They just have to be some kind of executable file.

+ +

HOOK SCRIPTS

+ +

If you want to run a specific script at a specific lifecycle event for ALL +packages, then you can use a hook script.

+ +

Place an executable file at node_modules/.hooks/{eventname}, and it'll get +run for all packages when they are going through that point in the package +lifecycle for any packages installed in that root.

+ +

Hook scripts are run exactly the same way as package.json scripts. That is, +they are in a separate child process, with the env described above.

+ +

BEST PRACTICES

+ + +
+ + + diff --git a/html/doc/search.html b/html/doc/search.html new file mode 100644 index 000000000..9a56dec40 --- /dev/null +++ b/html/doc/search.html @@ -0,0 +1,363 @@ + + + npm-search + + + +
+

npm-search(1) -- Search for packages

+ +

SYNOPSIS

+ +
npm search [search terms ...]
+ +

DESCRIPTION

+ +

Search the registry for packages matching the search terms.

+
+ + + diff --git a/html/doc/semver.html b/html/doc/semver.html new file mode 100644 index 000000000..11d75b368 --- /dev/null +++ b/html/doc/semver.html @@ -0,0 +1,443 @@ + + + npm-semver + + + +
+

semver(1) -- The semantic versioner for npm

+ +

Usage

+ +

As a node module:

+ +
$ npm install semver
+
+semver.valid('1.2.3') // true
+semver.valid('a.b.c') // false
+semver.clean('  =v1.2.3   ') // '1.2.3'
+semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
+semver.gt('1.2.3', '9.8.7') // false
+semver.lt('1.2.3', '9.8.7') // true
+ +

As a command-line utility:

+ +
$ npm install semver -g
+$ semver -h
+
+Usage: semver -v <version> [-r <range>]
+Test if version(s) satisfy the supplied range(s),
+and sort them.
+
+Multiple versions or ranges may be supplied.
+
+Program exits successfully if any valid version satisfies
+all supplied ranges, and prints all satisfying versions.
+
+If no versions are valid, or ranges are not satisfied,
+then exits failure.
+
+Versions are printed in ascending order, so supplying
+multiple versions to the utility will just sort them.
+ +

Versions

+ +

A version is the following things, in this order:

+ + + +

A leading "=" or "v" character is stripped off and ignored.

+ +

Comparisons

+ +

The ordering of versions is done using the following algorithm, given +two versions and asked to find the greater of the two:

+ + + +

Ranges

+ +

The following range styles are supported:

+ + + +

Ranges can be joined with either a space (which implies "and") or a +|| (which implies "or").

+ +

Functions

+ + + +

Comparison

+ + + +

Ranges

+ + +
+ + + diff --git a/html/doc/set.html b/html/doc/set.html new file mode 100644 index 000000000..646c79ce8 --- /dev/null +++ b/html/doc/set.html @@ -0,0 +1,871 @@ + + + npm-set + + + +
+

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 5 sources, in this priority:

+ + + +

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:

+ + + +

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 help scripts) +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

+ + + +

Force npm to always require authentication when accessing the registry, +even for GET requests.

+ +

bin-publish

+ + + +

If set to true, then binary packages will be created on publish.

+ +

This is the way to opt into the "bindist" behavior described below.

+ +

bindist

+ + + +

Experimental: on stable versions of node, binary distributions will be +created with this tag. If a user then installs that package, and their +bindist tag is found in the list of binary distributions, they will +get that prebuilt version.

+ +

Pre-build node packages have their preinstall, install, and postinstall +scripts stripped (since they are run prior to publishing), and do not +have their build directories automatically ignored.

+ +

It's yet to be seen if this is a good idea.

+ +

browser

+ + + +

The browser that is called by the npm docs command to open websites.

+ +

cache

+ + + +

The location of npm's cache directory. See npm help cache

+ +

color

+ + + +

If false, never shows colors. If "always" then always shows colors. +If true, then only prints color codes for tty file descriptors.

+ +

depth

+ + + +

The depth to go when recursing directories for npm ls and +npm cache ls.

+ +

description

+ + + +

Show the description in npm search

+ +

dev

+ + + +

Install dev-dependencies along with packages.

+ +

Note that dev-dependencies are also installed if the npat flag is +set.

+ +

editor

+ + + +

The command to run for npm edit or npm config edit.

+ +

force

+ + + +

Makes various commands more forceful.

+ + + +

global

+ + + +

Operates in "global" mode, so that packages are installed into the +prefix folder instead of the current working directory. See +npm help folders for more on the differences in behavior.

+ + + +

globalconfig

+ + + +

The config file to read for global config options.

+ +

globalignorefile

+ + + +

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

+ + + +

The group to use when running package scripts in global mode as the root +user.

+ +

gzipbin

+ + + +

The gzip binary

+ +

https-proxy

+ + + +

A proxy to use for outgoing https requests.

+ +

ignore

+ + + +

A white-space separated list of glob patterns of files to always exclude +from packages when building tarballs.

+ +

init.version

+ + + +

The value npm init should use by default for the package version.

+ +

init.author.name

+ + + +

The value npm init should use by default for the package author's name.

+ +

init.author.email

+ + + +

The value npm init should use by default for the package author's email.

+ +

init.author.url

+ + + +

The value npm init should use by default for the package author's homepage.

+ + + + + +

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:

+ + + +

logfd

+ + + +

The location to write log output.

+ +

loglevel

+ + + +

What level of logs to report. On failure, all logs are written to +npm-debug.log in the current working directory.

+ +

logprefix

+ + + +

Whether or not to prefix log messages with "npm" and the log level. See +also "color" and "loglevel".

+ +

long

+ + + +

Show extended information in npm ls

+ +

node-version

+ + + +

The node version to use when checking package's "engines" hash.

+ +

npat

+ + + +

Run tests on installation and report results to the +npaturl.

+ +

npaturl

+ + + +

The url to report npat test results.

+ +

onload-script

+ + + +

A node module to require() when npm loads. Useful for programmatic +usage.

+ +

outfd

+ + + +

Where to write "normal" output. This has no effect on log output.

+ +

parseable

+ + + +

Output parseable results from commands that write to +standard output.

+ +

prefix

+ + + +

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

+ + + +

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.
+ +

proxy

+ + + +

A proxy to use for outgoing http requests.

+ +

rebuild-bundle

+ + + +

Rebuild bundled dependencies after installation.

+ +

registry

+ + + +

The base URL of the npm package registry.

+ +

rollback

+ + + +

Remove failed installs.

+ +

save

+ + + +

Save installed packages to a package.json file as dependencies.

+ +

Only works if there is already a package.json file present.

+ +

searchopts

+ + + +

Space-separated options that are always passed to search.

+ +

searchexclude

+ + + +

Space-separated options that limit the results from search.

+ +

shell

+ + + +

The shell to run for the npm explore command.

+ +

tag

+ + + +

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.

+ +

tar

+ + + +

The tar executable

+ +

tmp

+ + + +

Where to store temporary files and folders. All temp files are deleted +on success, but left behind on failure for forensic purposes.

+ +

unicode

+ + + +

When set to true, npm uses unicode characters in the tree output. When +false, it uses ascii characters to draw trees.

+ +

unsafe-perm

+ + + +

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

+ + + +

Set to show short usage output (like the -H output) +instead of complete help when doing npm help.

+ +

user

+ + + +

The UID to set to when running package scripts as root.

+ +

username

+ + + +

The username on the npm registry. Set with npm adduser

+ +

userconfig

+ + + +

The location of user-level configuration settings.

+ +

userignorefile

+ + + +

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.

+ +

version

+ + + +

If true, output the npm version and exit successfully.

+ +

Only relevant when specified explicitly on the command line.

+ +

viewer

+ + + +

The program to use to view help content.

+ +

yes

+ + + +

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.

+
+ + + diff --git a/html/doc/start.html b/html/doc/start.html new file mode 100644 index 000000000..c6b13437b --- /dev/null +++ b/html/doc/start.html @@ -0,0 +1,363 @@ + + + npm-start + + + +
+

npm-start(1) -- Start a package

+ +

SYNOPSIS

+ +
npm start <name>
+ +

DESCRIPTION

+ +

This runs a package's "start" script, if one was provided.

+
+ + + diff --git a/html/doc/stop.html b/html/doc/stop.html new file mode 100644 index 000000000..7b44f0f0d --- /dev/null +++ b/html/doc/stop.html @@ -0,0 +1,363 @@ + + + npm-stop + + + +
+

npm-stop(1) -- Stop a package

+ +

SYNOPSIS

+ +
npm stop <name>
+ +

DESCRIPTION

+ +

This runs a package's "stop" script, if one was provided.

+
+ + + diff --git a/html/doc/submodule.html b/html/doc/submodule.html new file mode 100644 index 000000000..69f6ed4d2 --- /dev/null +++ b/html/doc/submodule.html @@ -0,0 +1,380 @@ + + + npm-submodule + + + +
+

npm-submodule(1) -- Add a package as a git submodule

+ +

SYNOPSIS

+ +
npm submodule <pkg>
+ +

DESCRIPTION

+ +

If the specified package has a git repository url in its package.json +description, then this command will add it as a git submodule at +node_modules/<pkg name>.

+ +

This is a convenience only. From then on, it's up to you to manage +updates by using the appropriate git commands. npm will stubbornly +refuse to update, modify, or remove anything with a .git subfolder +in it.

+ +

This command also does not install missing dependencies, if the package +does not include them in its git repository. If npm ls reports that +things are missing, you can either install, link, or submodule them yourself, +or you can do npm explore <pkgname> -- npm install to install the +dependencies into the submodule folder.

+ +

SEE ALSO

+ + +
+ + + diff --git a/html/doc/tag.html b/html/doc/tag.html new file mode 100644 index 000000000..cae5cec3a --- /dev/null +++ b/html/doc/tag.html @@ -0,0 +1,364 @@ + + + npm-tag + + + +
+

npm-tag(1) -- Tag a published version

+ +

SYNOPSIS

+ +
npm tag <name>@<version> [<tag>]
+ +

DESCRIPTION

+ +

Tags the specified version of the package with the specified tag, or the +--tag config if not specified.

+
+ + + diff --git a/html/doc/test.html b/html/doc/test.html new file mode 100644 index 000000000..724ccd534 --- /dev/null +++ b/html/doc/test.html @@ -0,0 +1,366 @@ + + + npm-test + + + +
+

npm-test(1) -- Test a package

+ +

SYNOPSIS

+ +
  npm test <name>
+ +

DESCRIPTION

+ +

This runs a package's "test" script, if one was provided.

+ +

To run tests as a condition of installation, set the npat config to +true.

+
+ + + diff --git a/html/doc/uninstall.html b/html/doc/uninstall.html new file mode 100644 index 000000000..c69bc2792 --- /dev/null +++ b/html/doc/uninstall.html @@ -0,0 +1,364 @@ + + + npm-uninstall + + + +
+

npm-uninstall(1) -- Remove a package

+ +

SYNOPSIS

+ +
npm uninstall <name>
+npm rm <name>
+ +

DESCRIPTION

+ +

This uninstalls a package, completely removing everything installed for it.

+
+ + + diff --git a/html/doc/unpublish.html b/html/doc/unpublish.html new file mode 100644 index 000000000..b7c4320bc --- /dev/null +++ b/html/doc/unpublish.html @@ -0,0 +1,367 @@ + + + npm-unpublish + + + +
+

npm-unpublish(1) -- Remove a package from the registry

+ +

SYNOPSIS

+ +
npm unpublish <name>[@<version>]
+ +

DESCRIPTION

+ +

This removes a package version from the registry, deleting its +entry and removing the tarball.

+ +

If no version is specified, or if all versions are removed then +the root package entry is removed from the registry entirely.

+
+ + + diff --git a/html/doc/update.html b/html/doc/update.html new file mode 100644 index 000000000..11f285692 --- /dev/null +++ b/html/doc/update.html @@ -0,0 +1,366 @@ + + + npm-update + + + +
+

npm-update(1) -- Update a package

+ +

SYNOPSIS

+ +
npm update [<name> [<name> ...]]
+ +

DESCRIPTION

+ +

This command will update all the packages listed to the latest version +(specified by the tag config).

+ +

It will also install missing packages.

+
+ + + diff --git a/html/doc/version.html b/html/doc/version.html new file mode 100644 index 000000000..616d67c52 --- /dev/null +++ b/html/doc/version.html @@ -0,0 +1,367 @@ + + + npm-version + + + +
+

npm-version(1) -- Bump a package version

+ +

SYNOPSIS

+ +
npm version <newversion>
+ +

DESCRIPTION

+ +

Run this in a package directory to bump the version and write the new +data back to the package.json file.

+ +

If run in a git repo, it will also create a version commit and tag, and +fail if the repo is not clean.

+
+ + + diff --git a/html/doc/view.html b/html/doc/view.html new file mode 100644 index 000000000..a0f56b1e7 --- /dev/null +++ b/html/doc/view.html @@ -0,0 +1,431 @@ + + + npm-view + + + +
+

npm-view(1) -- View registry info

+ +

SYNOPSIS

+ +
npm view <name>[@<version>] [<field>[.<subfield>]...]
+ +

DESCRIPTION

+ +

This command shows data about a package and prints it to the stream +referenced by the outfd config, which defaults to stdout.

+ +

To show the package registry entry for the connect package, you can do +this:

+ +
npm view connect
+ +

The default version is "latest" if unspecified.

+ +

Field names can be specified after the package descriptor. +For example, to show the dependencies of the ronn package at version +0.3.5, you could do the following:

+ +
npm view ronn@0.3.5 dependencies
+ +

You can view child field by separating them with a period. +To view the git repository URL for the latest version of npm, you could +do this:

+ +
npm view npm repository.url
+ +

This makes it easy to view information about a dependency with a bit of +shell scripting. For example, to view all the data about the version of +opts that ronn depends on, you can do this:

+ +
npm view opts@$(npm view ronn dependencies.opts)
+ +

For fields that are arrays, requesting a non-numeric field will return +all of the values from the objects in the list. For example, to get all +the contributor names for the "express" project, you can do this:

+ +
npm view express contributors.email
+ +

You may also use numeric indices in square braces to specifically select +an item in an array field. To just get the email address of the first +contributor in the list, you can do this:

+ +
npm view express contributors[0].email
+ +

Multiple fields may be specified, and will be printed one after another. +For exampls, to get all the contributor names and email addresses, you +can do this:

+ +
npm view express contributors.name contributors.email
+ +

"Person" fields are shown as a string if they would be shown as an +object. So, for example, this will show the list of npm contributors in +the shortened string format. (See npm help json for more on this.)

+ +
npm view npm contributors
+ +

If a version range is provided, then data will be printed for every +matching version of the package. This will show which version of jsdom +was required by each matching version of yui3:

+ +
npm view yui3@'>0.5.4' dependencies.jsdom
+ +

OUTPUT

+ +

If only a single string field for a single version is output, then it +will not be colorized or quoted, so as to enable piping the output to +another command.

+ +

If the version range matches multiple versions, than each printed value +will be prefixed with the version it applies to.

+ +

If multiple fields are requested, than each of them are prefixed with +the field name.

+
+ + + diff --git a/html/doc/whoami.html b/html/doc/whoami.html new file mode 100644 index 000000000..d523f4d5b --- /dev/null +++ b/html/doc/whoami.html @@ -0,0 +1,363 @@ + + + npm-whoami + + + +
+

npm-whoami(1) -- Display npm username

+ +

SYNOPSIS

+ +
npm whoami
+ +

DESCRIPTION

+ +

Print the username config to standard output.

+
+ + + diff --git a/html/docfoot.html b/html/docfoot.html new file mode 100644 index 000000000..11bc1276e --- /dev/null +++ b/html/docfoot.html @@ -0,0 +1,30 @@ + + + + diff --git a/html/dochead.html b/html/dochead.html new file mode 100644 index 000000000..c5ac218a6 --- /dev/null +++ b/html/dochead.html @@ -0,0 +1,324 @@ + + + npm-@NAME@ + + + +
-- cgit v1.2.3