| @@ -0,0 +1,211 @@ | ||
| npm-folders(5) -- Folder Structures Used by npm | ||
| =============================================== | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| npm puts various things on your computer. That's its job. | ||
|
|
||
| This document will tell you what it puts where. | ||
|
|
||
| ### tl;dr | ||
|
|
||
| * Local install (default): puts stuff in `./node_modules` of the current | ||
| package root. | ||
| * Global install (with `-g`): puts stuff in /usr/local or wherever node | ||
| is installed. | ||
| * Install it **locally** if you're going to `require()` it. | ||
| * Install it **globally** if you're going to run it on the command line. | ||
| * If you need both, then install it in both places, or use `npm link`. | ||
|
|
||
| ### prefix Configuration | ||
|
|
||
| The `prefix` config defaults to the location where node is installed. | ||
| On most systems, this is `/usr/local`, and most of the time is the same | ||
| as node's `process.installPrefix`. | ||
|
|
||
| On windows, this is the exact location of the node.exe binary. On Unix | ||
| systems, it's one level up, since node is typically installed at | ||
| `{prefix}/bin/node` rather than `{prefix}/node.exe`. | ||
|
|
||
| When the `global` flag is set, npm installs things into this prefix. | ||
| When it is not set, it uses the root of the current package, or the | ||
| current working directory if not in a package already. | ||
|
|
||
| ### Node Modules | ||
|
|
||
| Packages are dropped into the `node_modules` folder under the `prefix`. | ||
| When installing locally, this means that you can | ||
| `require("packagename")` to load its main module, or | ||
| `require("packagename/lib/path/to/sub/module")` to load other modules. | ||
|
|
||
| Global installs on Unix systems go to `{prefix}/lib/node_modules`. | ||
| Global installs on Windows go to `{prefix}/node_modules` (that is, no | ||
| `lib` folder.) | ||
|
|
||
| If you wish to `require()` a package, then install it locally. | ||
|
|
||
| ### Executables | ||
|
|
||
| When in global mode, executables are linked into `{prefix}/bin` on Unix, | ||
| or directly into `{prefix}` on Windows. | ||
|
|
||
| When in local mode, executables are linked into | ||
| `./node_modules/.bin` so that they can be made available to scripts run | ||
| through npm. (For example, so that a test runner will be in the path | ||
| when you run `npm test`.) | ||
|
|
||
| ### Man Pages | ||
|
|
||
| When in global mode, man pages are linked into `{prefix}/share/man`. | ||
|
|
||
| When in local mode, man pages are not installed. | ||
|
|
||
| Man pages are not installed on Windows systems. | ||
|
|
||
| ### Cache | ||
|
|
||
| See `npm-cache(1)`. Cache files are stored in `~/.npm` on Posix, or | ||
| `~/npm-cache` on Windows. | ||
|
|
||
| This is controlled by the `cache` configuration param. | ||
|
|
||
| ### Temp Files | ||
|
|
||
| Temporary files are stored by default in the folder specified by the | ||
| `tmp` config, which defaults to the TMPDIR, TMP, or TEMP environment | ||
| variables, or `/tmp` on Unix and `c:\windows\temp` on Windows. | ||
|
|
||
| Temp files are given a unique folder under this root for each run of the | ||
| program, and are deleted upon successful exit. | ||
|
|
||
| ## More Information | ||
|
|
||
| When installing locally, npm first tries to find an appropriate | ||
| `prefix` folder. This is so that `npm install foo@1.2.3` will install | ||
| to the sensible root of your package, even if you happen to have `cd`ed | ||
| into some other folder. | ||
|
|
||
| Starting at the $PWD, npm will walk up the folder tree checking for a | ||
| folder that contains either a `package.json` file, or a `node_modules` | ||
| folder. If such a thing is found, then that is treated as the effective | ||
| "current directory" for the purpose of running npm commands. (This | ||
| behavior is inspired by and similar to git's .git-folder seeking | ||
| logic when running git commands in a working dir.) | ||
|
|
||
| If no package root is found, then the current folder is used. | ||
|
|
||
| When you run `npm install foo@1.2.3`, then the package is loaded into | ||
| the cache, and then unpacked into `./node_modules/foo`. Then, any of | ||
| foo's dependencies are similarly unpacked into | ||
| `./node_modules/foo/node_modules/...`. | ||
|
|
||
| Any bin files are symlinked to `./node_modules/.bin/`, so that they may | ||
| be found by npm scripts when necessary. | ||
|
|
||
| ### Global Installation | ||
|
|
||
| If the `global` configuration is set to true, then npm will | ||
| install packages "globally". | ||
|
|
||
| For global installation, packages are installed roughly the same way, | ||
| but using the folders described above. | ||
|
|
||
| ### Cycles, Conflicts, and Folder Parsimony | ||
|
|
||
| Cycles are handled using the property of node's module system that it | ||
| walks up the directories looking for `node_modules` folders. So, at every | ||
| stage, if a package is already installed in an ancestor `node_modules` | ||
| folder, then it is not installed at the current location. | ||
|
|
||
| Consider the case above, where `foo -> bar -> baz`. Imagine if, in | ||
| addition to that, baz depended on bar, so you'd have: | ||
| `foo -> bar -> baz -> bar -> baz ...`. However, since the folder | ||
| structure is: `foo/node_modules/bar/node_modules/baz`, there's no need to | ||
| put another copy of bar into `.../baz/node_modules`, since when it calls | ||
| require("bar"), it will get the copy that is installed in | ||
| `foo/node_modules/bar`. | ||
|
|
||
| This shortcut is only used if the exact same | ||
| version would be installed in multiple nested `node_modules` folders. It | ||
| is still possible to have `a/node_modules/b/node_modules/a` if the two | ||
| "a" packages are different versions. However, without repeating the | ||
| exact same package multiple times, an infinite regress will always be | ||
| prevented. | ||
|
|
||
| Another optimization can be made by installing dependencies at the | ||
| highest level possible, below the localized "target" folder. | ||
|
|
||
| #### Example | ||
|
|
||
| Consider this dependency graph: | ||
|
|
||
| foo | ||
| +-- blerg@1.2.5 | ||
| +-- bar@1.2.3 | ||
| | +-- blerg@1.x (latest=1.3.7) | ||
| | +-- baz@2.x | ||
| | | `-- quux@3.x | ||
| | | `-- bar@1.2.3 (cycle) | ||
| | `-- asdf@* | ||
| `-- baz@1.2.3 | ||
| `-- quux@3.x | ||
| `-- bar | ||
|
|
||
| In this case, we might expect a folder structure like this: | ||
|
|
||
| foo | ||
| +-- node_modules | ||
| +-- blerg (1.2.5) <---[A] | ||
| +-- bar (1.2.3) <---[B] | ||
| | `-- node_modules | ||
| | +-- baz (2.0.2) <---[C] | ||
| | | `-- node_modules | ||
| | | `-- quux (3.2.0) | ||
| | `-- asdf (2.3.4) | ||
| `-- baz (1.2.3) <---[D] | ||
| `-- node_modules | ||
| `-- quux (3.2.0) <---[E] | ||
| Since foo depends directly on `bar@1.2.3` and `baz@1.2.3`, those are | ||
| installed in foo's `node_modules` folder. | ||
| Even though the latest copy of blerg is 1.3.7, foo has a specific | ||
| dependency on version 1.2.5. So, that gets installed at [A]. Since the | ||
| parent installation of blerg satisfies bar's dependency on `blerg@1.x`, | ||
| it does not install another copy under [B]. | ||
| Bar [B] also has dependencies on baz and asdf, so those are installed in | ||
| bar's `node_modules` folder. Because it depends on `baz@2.x`, it cannot | ||
| re-use the `baz@1.2.3` installed in the parent `node_modules` folder [D], | ||
| and must install its own copy [C]. | ||
| Underneath bar, the `baz -> quux -> bar` dependency creates a cycle. | ||
| However, because bar is already in quux's ancestry [B], it does not | ||
| unpack another copy of bar into that folder. | ||
| Underneath `foo -> baz` [D], quux's [E] folder tree is empty, because its | ||
| dependency on bar is satisfied by the parent folder copy installed at [B]. | ||
| For a graphical breakdown of what is installed where, use `npm ls`. | ||
| ### Publishing | ||
| Upon publishing, npm will look in the `node_modules` folder. If any of | ||
| the items there are not in the `bundledDependencies` array, then they will | ||
| not be included in the package tarball. | ||
| This allows a package maintainer to install all of their dependencies | ||
| (and dev dependencies) locally, but only re-publish those items that | ||
| cannot be found elsewhere. See `package.json(5)` for more information. | ||
| ## SEE ALSO | ||
| * npm-faq(7) | ||
| * package.json(5) | ||
| * npm-install(1) | ||
| * npm-pack(1) | ||
| * npm-cache(1) | ||
| * npm-config(1) | ||
| * npmrc(5) | ||
| * npm-config(7) | ||
| * npm-publish(1) |
| @@ -0,0 +1,59 @@ | ||
| npmrc(5) -- The npm config files | ||
| ================================ | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| npm gets its config settings from the command line, environment | ||
| variables, and `npmrc` files. | ||
|
|
||
| The `npm config` command can be used to update and edit the contents | ||
| of the user and global npmrc files. | ||
|
|
||
| For a list of available configuration options, see npm-config(7). | ||
|
|
||
| ## FILES | ||
|
|
||
| The three relevant files are: | ||
|
|
||
| * per-user config file (~/.npmrc) | ||
| * global config file ($PREFIX/npmrc) | ||
| * npm builtin config file (/path/to/npm/npmrc) | ||
|
|
||
| All npm config files are an ini-formatted list of `key = value` | ||
| parameters. Environment variables can be replaced using | ||
| `${VARIABLE_NAME}`. For example: | ||
|
|
||
| prefix = ${HOME}/.npm-packages | ||
|
|
||
| Each of these files is loaded, and config options are resolved in | ||
| priority order. For example, a setting in the userconfig file would | ||
| override the setting in the globalconfig file. | ||
|
|
||
| ### Per-user config file | ||
|
|
||
| `$HOME/.npmrc` (or the `userconfig` param, if set in the environment | ||
| or on the command line) | ||
|
|
||
| ### Global config file | ||
|
|
||
| `$PREFIX/etc/npmrc` (or the `globalconfig` param, if set above): | ||
| This file is an ini-file formatted list of `key = value` parameters. | ||
| Environment variables can be replaced as above. | ||
|
|
||
| ### Built-in config file | ||
|
|
||
| `path/to/npm/itself/npmrc` | ||
|
|
||
| This is an unchangeable "builtin" configuration file that npm keeps | ||
| consistent across updates. Set fields in here using the `./configure` | ||
| script that comes with npm. This is primarily for distribution | ||
| maintainers to override default configs in a standard and consistent | ||
| manner. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-folders(5) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * package.json(5) | ||
| * npm(1) |
| @@ -0,0 +1,181 @@ | ||
| npm-coding-style(7) -- npm's "funny" coding style | ||
| ================================================= | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| npm's coding style is a bit unconventional. It is not different for | ||
| difference's sake, but rather a carefully crafted style that is | ||
| designed to reduce visual clutter and make bugs more apparent. | ||
|
|
||
| If you want to contribute to npm (which is very encouraged), you should | ||
| make your code conform to npm's style. | ||
|
|
||
| Note: this concerns npm's code not the specific packages at npmjs.org | ||
|
|
||
| ## Line Length | ||
|
|
||
| Keep lines shorter than 80 characters. It's better for lines to be | ||
| too short than to be too long. Break up long lists, objects, and other | ||
| statements onto multiple lines. | ||
|
|
||
| ## Indentation | ||
|
|
||
| Two-spaces. Tabs are better, but they look like hell in web browsers | ||
| (and on github), and node uses 2 spaces, so that's that. | ||
|
|
||
| Configure your editor appropriately. | ||
|
|
||
| ## Curly braces | ||
|
|
||
| Curly braces belong on the same line as the thing that necessitates them. | ||
|
|
||
| Bad: | ||
|
|
||
| function () | ||
| { | ||
|
|
||
| Good: | ||
|
|
||
| function () { | ||
|
|
||
| If a block needs to wrap to the next line, use a curly brace. Don't | ||
| use it if it doesn't. | ||
|
|
||
| Bad: | ||
|
|
||
| if (foo) { bar() } | ||
| while (foo) | ||
| bar() | ||
|
|
||
| Good: | ||
|
|
||
| if (foo) bar() | ||
| while (foo) { | ||
| bar() | ||
| } | ||
|
|
||
| ## Semicolons | ||
|
|
||
| Don't use them except in four situations: | ||
|
|
||
| * `for (;;)` loops. They're actually required. | ||
| * null loops like: `while (something) ;` (But you'd better have a good | ||
| reason for doing that.) | ||
| * `case "foo": doSomething(); break` | ||
| * In front of a leading `(` or `[` at the start of the line. | ||
| This prevents the expression from being interpreted | ||
| as a function call or property access, respectively. | ||
|
|
||
| Some examples of good semicolon usage: | ||
|
|
||
| ;(x || y).doSomething() | ||
| ;[a, b, c].forEach(doSomething) | ||
| for (var i = 0; i < 10; i ++) { | ||
| switch (state) { | ||
| case "begin": start(); continue | ||
| case "end": finish(); break | ||
| default: throw new Error("unknown state") | ||
| } | ||
| end() | ||
| } | ||
|
|
||
| Note that starting lines with `-` and `+` also should be prefixed | ||
| with a semicolon, but this is much less common. | ||
|
|
||
| ## Comma First | ||
|
|
||
| If there is a list of things separated by commas, and it wraps | ||
| across multiple lines, put the comma at the start of the next | ||
| line, directly below the token that starts the list. Put the | ||
| final token in the list on a line by itself. For example: | ||
|
|
||
| var magicWords = [ "abracadabra" | ||
| , "gesundheit" | ||
| , "ventrilo" | ||
| ] | ||
| , spells = { "fireball" : function () { setOnFire() } | ||
| , "water" : function () { putOut() } | ||
| } | ||
| , a = 1 | ||
| , b = "abc" | ||
| , etc | ||
| , somethingElse | ||
|
|
||
| ## Whitespace | ||
|
|
||
| Put a single space in front of ( for anything other than a function call. | ||
| Also use a single space wherever it makes things more readable. | ||
|
|
||
| Don't leave trailing whitespace at the end of lines. Don't indent empty | ||
| lines. Don't use more spaces than are helpful. | ||
|
|
||
| ## Functions | ||
|
|
||
| Use named functions. They make stack traces a lot easier to read. | ||
|
|
||
| ## Callbacks, Sync/async Style | ||
|
|
||
| Use the asynchronous/non-blocking versions of things as much as possible. | ||
| It might make more sense for npm to use the synchronous fs APIs, but this | ||
| way, the fs and http and child process stuff all uses the same callback-passing | ||
| methodology. | ||
|
|
||
| The callback should always be the last argument in the list. Its first | ||
| argument is the Error or null. | ||
|
|
||
| Be very careful never to ever ever throw anything. It's worse than useless. | ||
| Just send the error message back as the first argument to the callback. | ||
|
|
||
| ## Errors | ||
|
|
||
| Always create a new Error object with your message. Don't just return a | ||
| string message to the callback. Stack traces are handy. | ||
|
|
||
| ## Logging | ||
|
|
||
| Logging is done using the [npmlog](https://github.com/npm/npmlog) | ||
| utility. | ||
|
|
||
| Please clean up logs when they are no longer helpful. In particular, | ||
| logging the same object over and over again is not helpful. Logs should | ||
| report what's happening so that it's easier to track down where a fault | ||
| occurs. | ||
|
|
||
| Use appropriate log levels. See `npm-config(7)` and search for | ||
| "loglevel". | ||
|
|
||
| ## Case, naming, etc. | ||
|
|
||
| Use `lowerCamelCase` for multiword identifiers when they refer to objects, | ||
| functions, methods, members, or anything not specified in this section. | ||
|
|
||
| Use `UpperCamelCase` for class names (things that you'd pass to "new"). | ||
|
|
||
| Use `all-lower-hyphen-css-case` for multiword filenames and config keys. | ||
|
|
||
| Use named functions. They make stack traces easier to follow. | ||
|
|
||
| Use `CAPS_SNAKE_CASE` for constants, things that should never change | ||
| and are rarely used. | ||
|
|
||
| Use a single uppercase letter for function names where the function | ||
| would normally be anonymous, but needs to call itself recursively. It | ||
| makes it clear that it's a "throwaway" function. | ||
|
|
||
| ## null, undefined, false, 0 | ||
|
|
||
| Boolean variables and functions should always be either `true` or | ||
| `false`. Don't set it to 0 unless it's supposed to be a number. | ||
|
|
||
| When something is intentionally missing or removed, set it to `null`. | ||
|
|
||
| Don't set things to `undefined`. Reserve that value to mean "not yet | ||
| set to anything." | ||
|
|
||
| Boolean objects are verboten. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-developers(7) | ||
| * npm-faq(7) | ||
| * npm(1) |
| @@ -0,0 +1,207 @@ | ||
| npm-developers(7) -- Developer Guide | ||
| ==================================== | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| So, you've decided to use npm to develop (and maybe publish/deploy) | ||
| your project. | ||
|
|
||
| Fantastic! | ||
|
|
||
| There are a few things that you need to do above the simple steps | ||
| that your users will do to install your program. | ||
|
|
||
| ## About These Documents | ||
|
|
||
| These are man pages. If you install npm, you should be able to | ||
| then do `man npm-thing` to get the documentation on a particular | ||
| topic, or `npm help thing` to see the same information. | ||
|
|
||
| ## What is a `package` | ||
|
|
||
| A package is: | ||
|
|
||
| * a) a folder containing a program described by a package.json file | ||
| * b) a gzipped tarball containing (a) | ||
| * c) a url that resolves to (b) | ||
| * d) a `<name>@<version>` that is published on the registry with (c) | ||
| * e) a `<name>@<tag>` that points to (d) | ||
| * f) a `<name>` that has a "latest" tag satisfying (e) | ||
| * g) a `git` url that, when cloned, results in (a). | ||
|
|
||
| Even if you never publish your package, you can still get a lot of | ||
| benefits of using npm if you just want to write a node program (a), and | ||
| perhaps if you also want to be able to easily install it elsewhere | ||
| after packing it up into a tarball (b). | ||
|
|
||
| Git urls can be of the form: | ||
|
|
||
| git://github.com/user/project.git#commit-ish | ||
| git+ssh://user@hostname:project.git#commit-ish | ||
| git+http://user@hostname/project/blah.git#commit-ish | ||
| git+https://user@hostname/project/blah.git#commit-ish | ||
|
|
||
| The `commit-ish` can be any tag, sha, or branch which can be supplied as | ||
| an argument to `git checkout`. The default is `master`. | ||
|
|
||
| ## The package.json File | ||
|
|
||
| You need to have a `package.json` file in the root of your project to do | ||
| much of anything with npm. That is basically the whole interface. | ||
|
|
||
| See `package.json(5)` for details about what goes in that file. At the very | ||
| least, you need: | ||
|
|
||
| * name: | ||
| This should be a string that identifies your project. Please do not | ||
| use the name to specify that it runs on node, or is in JavaScript. | ||
| You can use the "engines" field to explicitly state the versions of | ||
| node (or whatever else) that your program requires, and it's pretty | ||
| well assumed that it's javascript. | ||
|
|
||
| It does not necessarily need to match your github repository name. | ||
|
|
||
| So, `node-foo` and `bar-js` are bad names. `foo` or `bar` are better. | ||
|
|
||
| * version: | ||
| A semver-compatible version. | ||
|
|
||
| * engines: | ||
| Specify the versions of node (or whatever else) that your program | ||
| runs on. The node API changes a lot, and there may be bugs or new | ||
| functionality that you depend on. Be explicit. | ||
|
|
||
| * author: | ||
| Take some credit. | ||
|
|
||
| * scripts: | ||
| If you have a special compilation or installation script, then you | ||
| should put it in the `scripts` hash. You should definitely have at | ||
| least a basic smoke-test command as the "scripts.test" field. | ||
| See npm-scripts(7). | ||
|
|
||
| * main: | ||
| If you have a single module that serves as the entry point to your | ||
| program (like what the "foo" package gives you at require("foo")), | ||
| then you need to specify that in the "main" field. | ||
|
|
||
| * directories: | ||
| This is a hash of folders. The best ones to include are "lib" and | ||
| "doc", but if you specify a folder full of man pages in "man", then | ||
| they'll get installed just like these ones. | ||
|
|
||
| You can use `npm init` in the root of your package in order to get you | ||
| started with a pretty basic package.json file. See `npm-init(1)` for | ||
| more info. | ||
|
|
||
| ## Keeping files *out* of your package | ||
|
|
||
| Use a `.npmignore` file to keep stuff out of your package. If there's | ||
| no `.npmignore` file, but there *is* a `.gitignore` file, then npm will | ||
| ignore the stuff matched by the `.gitignore` file. If you *want* to | ||
| include something that is excluded by your `.gitignore` file, you can | ||
| create an empty `.npmignore` file to override it. | ||
|
|
||
| By default, the following paths and files are ignored, so there's no | ||
| need to add them to `.npmignore` explicitly: | ||
|
|
||
| * `.*.swp` | ||
| * `._*` | ||
| * `.DS_Store` | ||
| * `.git` | ||
| * `.hg` | ||
| * `.lock-wscript` | ||
| * `.svn` | ||
| * `.wafpickle-*` | ||
| * `CVS` | ||
| * `npm-debug.log` | ||
|
|
||
| Additionally, everything in `node_modules` is ignored, except for | ||
| bundled dependencies. npm automatically handles this for you, so don't | ||
| bother adding `node_modules` to `.npmignore`. | ||
|
|
||
| The following paths and files are never ignored, so adding them to | ||
| `.npmignore` is pointless: | ||
|
|
||
| * `package.json` | ||
| * `README.*` | ||
|
|
||
| ## Link Packages | ||
|
|
||
| `npm link` is designed to install a development package and see the | ||
| changes in real time without having to keep re-installing it. (You do | ||
| need to either re-link or `npm rebuild -g` to update compiled packages, | ||
| of course.) | ||
|
|
||
| More info at `npm-link(1)`. | ||
|
|
||
| ## Before Publishing: Make Sure Your Package Installs and Works | ||
|
|
||
| **This is important.** | ||
|
|
||
| If you can not install it locally, you'll have | ||
| problems trying to publish it. Or, worse yet, you'll be able to | ||
| publish it, but you'll be publishing a broken or pointless package. | ||
| So don't do that. | ||
|
|
||
| In the root of your package, do this: | ||
|
|
||
| npm install . -g | ||
|
|
||
| That'll show you that it's working. If you'd rather just create a symlink | ||
| package that points to your working directory, then do this: | ||
|
|
||
| npm link | ||
|
|
||
| Use `npm ls -g` to see if it's there. | ||
|
|
||
| To test a local install, go into some other folder, and then do: | ||
|
|
||
| cd ../some-other-folder | ||
| npm install ../my-package | ||
|
|
||
| to install it locally into the node_modules folder in that other place. | ||
|
|
||
| Then go into the node-repl, and try using require("my-thing") to | ||
| bring in your module's main module. | ||
|
|
||
| ## Create a User Account | ||
|
|
||
| Create a user with the adduser command. It works like this: | ||
|
|
||
| npm adduser | ||
|
|
||
| and then follow the prompts. | ||
|
|
||
| This is documented better in npm-adduser(1). | ||
|
|
||
| ## Publish your package | ||
|
|
||
| This part's easy. IN the root of your folder, do this: | ||
|
|
||
| npm publish | ||
|
|
||
| You can give publish a url to a tarball, or a filename of a tarball, | ||
| or a path to a folder. | ||
|
|
||
| Note that pretty much **everything in that folder will be exposed** | ||
| by default. So, if you have secret stuff in there, use a | ||
| `.npmignore` file to list out the globs to ignore, or publish | ||
| from a fresh checkout. | ||
|
|
||
| ## Brag about it | ||
|
|
||
| Send emails, write blogs, blab in IRC. | ||
|
|
||
| Tell the world how easy it is to install your program! | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-faq(7) | ||
| * npm(1) | ||
| * npm-init(1) | ||
| * package.json(5) | ||
| * npm-scripts(7) | ||
| * npm-publish(1) | ||
| * npm-adduser(1) | ||
| * npm-registry(7) |
| @@ -0,0 +1,99 @@ | ||
| npm-disputes(7) -- Handling Module Name Disputes | ||
| ================================================ | ||
|
|
||
| ## SYNOPSIS | ||
|
|
||
| 1. Get the author email with `npm owner ls <pkgname>` | ||
| 2. Email the author, CC <support@npmjs.com> | ||
| 3. After a few weeks, if there's no resolution, we'll sort it out. | ||
|
|
||
| Don't squat on package names. Publish code or move out of the way. | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| There sometimes arise cases where a user publishes a module, and then | ||
| later, some other user wants to use that name. Here are some common | ||
| ways that happens (each of these is based on actual events.) | ||
|
|
||
| 1. Joe writes a JavaScript module `foo`, which is not node-specific. | ||
| Joe doesn't use node at all. Bob wants to use `foo` in node, so he | ||
| wraps it in an npm module. Some time later, Joe starts using node, | ||
| and wants to take over management of his program. | ||
| 2. Bob writes an npm module `foo`, and publishes it. Perhaps much | ||
| later, Joe finds a bug in `foo`, and fixes it. He sends a pull | ||
| request to Bob, but Bob doesn't have the time to deal with it, | ||
| because he has a new job and a new baby and is focused on his new | ||
| erlang project, and kind of not involved with node any more. Joe | ||
| would like to publish a new `foo`, but can't, because the name is | ||
| taken. | ||
| 3. Bob writes a 10-line flow-control library, and calls it `foo`, and | ||
| publishes it to the npm registry. Being a simple little thing, it | ||
| never really has to be updated. Joe works for Foo Inc, the makers | ||
| of the critically acclaimed and widely-marketed `foo` JavaScript | ||
| toolkit framework. They publish it to npm as `foojs`, but people are | ||
| routinely confused when `npm install foo` is some different thing. | ||
| 4. Bob writes a parser for the widely-known `foo` file format, because | ||
| he needs it for work. Then, he gets a new job, and never updates the | ||
| prototype. Later on, Joe writes a much more complete `foo` parser, | ||
| but can't publish, because Bob's `foo` is in the way. | ||
|
|
||
| The validity of Joe's claim in each situation can be debated. However, | ||
| Joe's appropriate course of action in each case is the same. | ||
|
|
||
| 1. `npm owner ls foo`. This will tell Joe the email address of the | ||
| owner (Bob). | ||
| 2. Joe emails Bob, explaining the situation **as respectfully as | ||
| possible**, and what he would like to do with the module name. He | ||
| adds the npm support staff <support@npmjs.com> to the CC list of | ||
| the email. Mention in the email that Bob can run `npm owner add | ||
| joe foo` to add Joe as an owner of the `foo` package. | ||
| 3. After a reasonable amount of time, if Bob has not responded, or if | ||
| Bob and Joe can't come to any sort of resolution, email support | ||
| <support@npmjs.com> and we'll sort it out. ("Reasonable" is | ||
| usually at least 4 weeks, but extra time is allowed around common | ||
| holidays.) | ||
|
|
||
| ## REASONING | ||
|
|
||
| In almost every case so far, the parties involved have been able to reach | ||
| an amicable resolution without any major intervention. Most people | ||
| really do want to be reasonable, and are probably not even aware that | ||
| they're in your way. | ||
|
|
||
| Module ecosystems are most vibrant and powerful when they are as | ||
| self-directed as possible. If an admin one day deletes something you | ||
| had worked on, then that is going to make most people quite upset, | ||
| regardless of the justification. When humans solve their problems by | ||
| talking to other humans with respect, everyone has the chance to end up | ||
| feeling good about the interaction. | ||
|
|
||
| ## EXCEPTIONS | ||
|
|
||
| Some things are not allowed, and will be removed without discussion if | ||
| they are brought to the attention of the npm registry admins, including | ||
| but not limited to: | ||
|
|
||
| 1. Malware (that is, a package designed to exploit or harm the machine on | ||
| which it is installed). | ||
| 2. Violations of copyright or licenses (for example, cloning an | ||
| MIT-licensed program, and then removing or changing the copyright and | ||
| license statement). | ||
| 3. Illegal content. | ||
| 4. "Squatting" on a package name that you *plan* to use, but aren't | ||
| actually using. Sorry, I don't care how great the name is, or how | ||
| perfect a fit it is for the thing that someday might happen. If | ||
| someone wants to use it today, and you're just taking up space with | ||
| an empty tarball, you're going to be evicted. | ||
| 5. Putting empty packages in the registry. Packages must have SOME | ||
| functionality. It can be silly, but it can't be *nothing*. (See | ||
| also: squatting.) | ||
| 6. Doing weird things with the registry, like using it as your own | ||
| personal application database or otherwise putting non-packagey | ||
| things into it. | ||
|
|
||
| If you see bad behavior like this, please report it right away. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-registry(7) | ||
| * npm-owner(1) |
| @@ -0,0 +1,364 @@ | ||
| npm-faq(7) -- Frequently Asked Questions | ||
| ======================================== | ||
|
|
||
| ## Where can I find these docs in HTML? | ||
|
|
||
| <https://www.npmjs.org/doc/>, or run: | ||
|
|
||
| npm config set viewer browser | ||
|
|
||
| to open these documents in your default web browser rather than `man`. | ||
|
|
||
| ## It didn't work. | ||
|
|
||
| That's not really a question. | ||
|
|
||
| ## Why didn't it work? | ||
|
|
||
| I don't know yet. | ||
|
|
||
| Read the error output, and if you can't figure out what it means, | ||
| do what it says and post a bug with all the information it asks for. | ||
|
|
||
| ## Where does npm put stuff? | ||
|
|
||
| See `npm-folders(5)` | ||
|
|
||
| tl;dr: | ||
|
|
||
| * Use the `npm root` command to see where modules go, and the `npm bin` | ||
| command to see where executables go | ||
| * Global installs are different from local installs. If you install | ||
| something with the `-g` flag, then its executables go in `npm bin -g` | ||
| and its modules go in `npm root -g`. | ||
|
|
||
| ## How do I install something on my computer in a central location? | ||
|
|
||
| Install it globally by tacking `-g` or `--global` to the command. (This | ||
| is especially important for command line utilities that need to add | ||
| their bins to the global system `PATH`.) | ||
|
|
||
| ## I installed something globally, but I can't `require()` it | ||
|
|
||
| Install it locally. | ||
|
|
||
| The global install location is a place for command-line utilities | ||
| to put their bins in the system `PATH`. It's not for use with `require()`. | ||
|
|
||
| If you `require()` a module in your code, then that means it's a | ||
| dependency, and a part of your program. You need to install it locally | ||
| in your program. | ||
|
|
||
| ## Why can't npm just put everything in one place, like other package managers? | ||
|
|
||
| Not every change is an improvement, but every improvement is a change. | ||
| This would be like asking git to do network IO for every commit. It's | ||
| not going to happen, because it's a terrible idea that causes more | ||
| problems than it solves. | ||
|
|
||
| It is much harder to avoid dependency conflicts without nesting | ||
| dependencies. This is fundamental to the way that npm works, and has | ||
| proven to be an extremely successful approach. See `npm-folders(5)` for | ||
| more details. | ||
|
|
||
| If you want a package to be installed in one place, and have all your | ||
| programs reference the same copy of it, then use the `npm link` command. | ||
| That's what it's for. Install it globally, then link it into each | ||
| program that uses it. | ||
|
|
||
| ## Whatever, I really want the old style 'everything global' style. | ||
|
|
||
| Write your own package manager. You could probably even wrap up `npm` | ||
| in a shell script if you really wanted to. | ||
|
|
||
| npm will not help you do something that is known to be a bad idea. | ||
|
|
||
| ## Should I check my `node_modules` folder into git? | ||
|
|
||
| Mikeal Rogers answered this question very well: | ||
|
|
||
| <http://www.futurealoof.com/posts/nodemodules-in-git.html> | ||
|
|
||
| tl;dr | ||
|
|
||
| * Check `node_modules` into git for things you **deploy**, such as | ||
| websites and apps. | ||
| * Do not check `node_modules` into git for libraries and modules | ||
| intended to be reused. | ||
| * Use npm to manage dependencies in your dev environment, but not in | ||
| your deployment scripts. | ||
|
|
||
| ## Is it 'npm' or 'NPM' or 'Npm'? | ||
|
|
||
| npm should never be capitalized unless it is being displayed in a | ||
| location that is customarily all-caps (such as the title of man pages.) | ||
|
|
||
| ## If 'npm' is an acronym, why is it never capitalized? | ||
|
|
||
| Contrary to the belief of many, "npm" is not in fact an abbreviation for | ||
| "Node Package Manager". It is a recursive bacronymic abbreviation for | ||
| "npm is not an acronym". (If it was "ninaa", then it would be an | ||
| acronym, and thus incorrectly named.) | ||
|
|
||
| "NPM", however, *is* an acronym (more precisely, a capitonym) for the | ||
| National Association of Pastoral Musicians. You can learn more | ||
| about them at <http://npm.org/>. | ||
|
|
||
| In software, "NPM" is a Non-Parametric Mapping utility written by | ||
| Chris Rorden. You can analyze pictures of brains with it. Learn more | ||
| about the (capitalized) NPM program at <http://www.cabiatl.com/mricro/npm/>. | ||
|
|
||
| The first seed that eventually grew into this flower was a bash utility | ||
| named "pm", which was a shortened descendent of "pkgmakeinst", a | ||
| bash function that was used to install various different things on different | ||
| platforms, most often using Yahoo's `yinst`. If `npm` was ever an | ||
| acronym for anything, it was `node pm` or maybe `new pm`. | ||
|
|
||
| So, in all seriousness, the "npm" project is named after its command-line | ||
| utility, which was organically selected to be easily typed by a right-handed | ||
| programmer using a US QWERTY keyboard layout, ending with the | ||
| right-ring-finger in a postition to type the `-` key for flags and | ||
| other command-line arguments. That command-line utility is always | ||
| lower-case, though it starts most sentences it is a part of. | ||
|
|
||
| ## How do I list installed packages? | ||
|
|
||
| `npm ls` | ||
|
|
||
| ## How do I search for packages? | ||
|
|
||
| `npm search` | ||
|
|
||
| Arguments are greps. `npm search jsdom` shows jsdom packages. | ||
|
|
||
| ## How do I update npm? | ||
|
|
||
| npm update npm -g | ||
|
|
||
| You can also update all outdated local packages by doing `npm update` without | ||
| any arguments, or global packages by doing `npm update -g`. | ||
|
|
||
| Occasionally, the version of npm will progress such that the current | ||
| version cannot be properly installed with the version that you have | ||
| installed already. (Consider, if there is ever a bug in the `update` | ||
| command.) | ||
|
|
||
| In those cases, you can do this: | ||
|
|
||
| curl https://www.npmjs.org/install.sh | sh | ||
|
|
||
| ## What is a `package`? | ||
|
|
||
| A package is: | ||
|
|
||
| * a) a folder containing a program described by a package.json file | ||
| * b) a gzipped tarball containing (a) | ||
| * c) a url that resolves to (b) | ||
| * d) a `<name>@<version>` that is published on the registry with (c) | ||
| * e) a `<name>@<tag>` that points to (d) | ||
| * f) a `<name>` that has a "latest" tag satisfying (e) | ||
| * g) a `git` url that, when cloned, results in (a). | ||
|
|
||
| Even if you never publish your package, you can still get a lot of | ||
| benefits of using npm if you just want to write a node program (a), and | ||
| perhaps if you also want to be able to easily install it elsewhere | ||
| after packing it up into a tarball (b). | ||
|
|
||
| Git urls can be of the form: | ||
|
|
||
| git://github.com/user/project.git#commit-ish | ||
| git+ssh://user@hostname:project.git#commit-ish | ||
| git+http://user@hostname/project/blah.git#commit-ish | ||
| git+https://user@hostname/project/blah.git#commit-ish | ||
|
|
||
| The `commit-ish` can be any tag, sha, or branch which can be supplied as | ||
| an argument to `git checkout`. The default is `master`. | ||
|
|
||
| ## What is a `module`? | ||
|
|
||
| A module is anything that can be loaded with `require()` in a Node.js | ||
| program. The following things are all examples of things that can be | ||
| loaded as modules: | ||
|
|
||
| * A folder with a `package.json` file containing a `main` field. | ||
| * A folder with an `index.js` file in it. | ||
| * A JavaScript file. | ||
|
|
||
| Most npm packages are modules, because they are libraries that you | ||
| load with `require`. However, there's no requirement that an npm | ||
| package be a module! Some only contain an executable command-line | ||
| interface, and don't provide a `main` field for use in Node programs. | ||
|
|
||
| Almost all npm packages (at least, those that are Node programs) | ||
| *contain* many modules within them (because every file they load with | ||
| `require()` is a module). | ||
|
|
||
| In the context of a Node program, the `module` is also the thing that | ||
| was loaded *from* a file. For example, in the following program: | ||
|
|
||
| var req = require('request') | ||
|
|
||
| we might say that "The variable `req` refers to the `request` module". | ||
|
|
||
| ## So, why is it the "`node_modules`" folder, but "`package.json`" file? Why not `node_packages` or `module.json`? | ||
|
|
||
| The `package.json` file defines the package. (See "What is a | ||
| package?" above.) | ||
|
|
||
| The `node_modules` folder is the place Node.js looks for modules. | ||
| (See "What is a module?" above.) | ||
|
|
||
| For example, if you create a file at `node_modules/foo.js` and then | ||
| had a program that did `var f = require('foo.js')` then it would load | ||
| the module. However, `foo.js` is not a "package" in this case, | ||
| because it does not have a package.json. | ||
|
|
||
| Alternatively, if you create a package which does not have an | ||
| `index.js` or a `"main"` field in the `package.json` file, then it is | ||
| not a module. Even if it's installed in `node_modules`, it can't be | ||
| an argument to `require()`. | ||
|
|
||
| ## `"node_modules"` is the name of my deity's arch-rival, and a Forbidden Word in my religion. Can I configure npm to use a different folder? | ||
|
|
||
| No. This will never happen. This question comes up sometimes, | ||
| because it seems silly from the outside that npm couldn't just be | ||
| configured to put stuff somewhere else, and then npm could load them | ||
| from there. It's an arbitrary spelling choice, right? What's the big | ||
| deal? | ||
|
|
||
| At the time of this writing, the string `'node_modules'` appears 151 | ||
| times in 53 separate files in npm and node core (excluding tests and | ||
| documentation). | ||
|
|
||
| Some of these references are in node's built-in module loader. Since | ||
| npm is not involved **at all** at run-time, node itself would have to | ||
| be configured to know where you've decided to stick stuff. Complexity | ||
| hurdle #1. Since the Node module system is locked, this cannot be | ||
| changed, and is enough to kill this request. But I'll continue, in | ||
| deference to your deity's delicate feelings regarding spelling. | ||
|
|
||
| Many of the others are in dependencies that npm uses, which are not | ||
| necessarily tightly coupled to npm (in the sense that they do not read | ||
| npm's configuration files, etc.) Each of these would have to be | ||
| configured to take the name of the `node_modules` folder as a | ||
| parameter. Complexity hurdle #2. | ||
|
|
||
| Furthermore, npm has the ability to "bundle" dependencies by adding | ||
| the dep names to the `"bundledDependencies"` list in package.json, | ||
| which causes the folder to be included in the package tarball. What | ||
| if the author of a module bundles its dependencies, and they use a | ||
| different spelling for `node_modules`? npm would have to rename the | ||
| folder at publish time, and then be smart enough to unpack it using | ||
| your locally configured name. Complexity hurdle #3. | ||
|
|
||
| Furthermore, what happens when you *change* this name? Fine, it's | ||
| easy enough the first time, just rename the `node_modules` folders to | ||
| `./blergyblerp/` or whatever name you choose. But what about when you | ||
| change it again? npm doesn't currently track any state about past | ||
| configuration settings, so this would be rather difficult to do | ||
| properly. It would have to track every previous value for this | ||
| config, and always accept any of them, or else yesterday's install may | ||
| be broken tomorrow. Complexity hurdle #5. | ||
|
|
||
| Never going to happen. The folder is named `node_modules`. It is | ||
| written indelibly in the Node Way, handed down from the ancient times | ||
| of Node 0.3. | ||
|
|
||
| ## How do I install node with npm? | ||
|
|
||
| You don't. Try one of these node version managers: | ||
|
|
||
| Unix: | ||
|
|
||
| * <http://github.com/isaacs/nave> | ||
| * <http://github.com/visionmedia/n> | ||
| * <http://github.com/creationix/nvm> | ||
|
|
||
| Windows: | ||
|
|
||
| * <http://github.com/marcelklehr/nodist> | ||
| * <https://github.com/hakobera/nvmw> | ||
| * <https://github.com/nanjingboy/nvmw> | ||
|
|
||
| ## How can I use npm for development? | ||
|
|
||
| See `npm-developers(7)` and `package.json(5)`. | ||
|
|
||
| You'll most likely want to `npm link` your development folder. That's | ||
| awesomely handy. | ||
|
|
||
| To set up your own private registry, check out `npm-registry(7)`. | ||
|
|
||
| ## Can I list a url as a dependency? | ||
|
|
||
| Yes. It should be a url to a gzipped tarball containing a single folder | ||
| that has a package.json in its root, or a git url. | ||
| (See "what is a package?" above.) | ||
|
|
||
| ## How do I symlink to a dev folder so I don't have to keep re-installing? | ||
|
|
||
| See `npm-link(1)` | ||
|
|
||
| ## The package registry website. What is that exactly? | ||
|
|
||
| See `npm-registry(7)`. | ||
|
|
||
| ## I forgot my password, and can't publish. How do I reset it? | ||
|
|
||
| Go to <https://npmjs.org/forgot>. | ||
|
|
||
| ## I get ECONNREFUSED a lot. What's up? | ||
|
|
||
| Either the registry is down, or node's DNS isn't able to reach out. | ||
|
|
||
| To check if the registry is down, open up | ||
| <https://registry.npmjs.org/> in a web browser. This will also tell | ||
| you if you are just unable to access the internet for some reason. | ||
|
|
||
| If the registry IS down, let us know by emailing <support@npmjs.com> | ||
| or posting an issue at <https://github.com/npm/npm/issues>. If it's | ||
| down for the world (and not just on your local network) then we're | ||
| probably already being pinged about it. | ||
|
|
||
| You can also often get a faster response by visiting the #npm channel | ||
| on Freenode IRC. | ||
|
|
||
| ## Why no namespaces? | ||
|
|
||
| Please see this discussion: <https://github.com/npm/npm/issues/798> | ||
|
|
||
| tl;dr - It doesn't actually make things better, and can make them worse. | ||
|
|
||
| If you want to namespace your own packages, you may: simply use the | ||
| `-` character to separate the names. npm is a mostly anarchic system. | ||
| There is not sufficient need to impose namespace rules on everyone. | ||
|
|
||
| ## Who does npm? | ||
|
|
||
| npm was originally written by Isaac Z. Schlueter, and many others have | ||
| contributed to it, some of them quite substantially. | ||
|
|
||
| The npm open source project, The npm Registry, and [the community | ||
| website](https://www.npmjs.org) are maintained and operated by the | ||
| good folks at [npm, Inc.](https://www.npmjs.com) | ||
|
|
||
| ## I have a question or request not addressed here. Where should I put it? | ||
|
|
||
| Post an issue on the github project: | ||
|
|
||
| * <https://github.com/npm/npm/issues> | ||
|
|
||
| ## Why does npm hate me? | ||
|
|
||
| npm is not capable of hatred. It loves everyone, especially you. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm(1) | ||
| * npm-developers(7) | ||
| * package.json(5) | ||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) | ||
| * npm-config(7) | ||
| * npm-folders(5) |
| @@ -0,0 +1,69 @@ | ||
| npm-registry(7) -- 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.iriscouch.com/registry>. The code for the couchapp is | ||
| available at <http://github.com/npm/npmjs.org>. npm user accounts | ||
| are CouchDB users, stored in the <http://isaacs.iriscouch.com/_users> | ||
| database. | ||
|
|
||
| The registry URL is supplied by the `registry` config parameter. See | ||
| `npm-config(1)`, `npmrc(5)`, and `npm-config(7)` 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 `package.json(5)` 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. Basically, yes, you do, or you have to | ||
| effectively implement the entire CouchDB API anyway. | ||
|
|
||
| ## Is there a website or something to see package docs and such? | ||
|
|
||
| Yes, head over to <https://npmjs.org/> | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-config(1) | ||
| * npm-config(7) | ||
| * npmrc(5) | ||
| * npm-developers(7) | ||
| * npm-disputes(7) |
| @@ -0,0 +1,245 @@ | ||
| npm-scripts(7) -- How npm handles the "scripts" field | ||
| ===================================================== | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| npm supports the "scripts" member of the package.json script, for the | ||
| following scripts: | ||
|
|
||
| * prepublish: | ||
| Run BEFORE the package is published. (Also run on local `npm | ||
| install` without any arguments.) | ||
| * publish, postpublish: | ||
| Run AFTER the package is published. | ||
| * preinstall: | ||
| Run BEFORE the package is installed | ||
| * install, postinstall: | ||
| Run AFTER the package is installed. | ||
| * preuninstall, uninstall: | ||
| Run BEFORE the package is uninstalled. | ||
| * postuninstall: | ||
| Run AFTER the package is uninstalled. | ||
| * preupdate: | ||
| Run BEFORE the package is updated with the update command. | ||
| * update, postupdate: | ||
| Run AFTER the package is updated with the update command. | ||
| * pretest, test, posttest: | ||
| Run by the `npm test` command. | ||
| * prestop, stop, poststop: | ||
| Run by the `npm stop` command. | ||
| * prestart, start, poststart: | ||
| Run by the `npm start` command. | ||
| * prerestart, restart, postrestart: | ||
| Run by the `npm restart` command. Note: `npm restart` will run the | ||
| stop and start scripts if no `restart` script is provided. | ||
|
|
||
| Additionally, arbitrary scripts can be run by doing | ||
| `npm run-script <stage> <pkg>`. | ||
|
|
||
| ## NOTE: INSTALL SCRIPTS ARE AN ANTIPATTERN | ||
|
|
||
| **tl;dr** Don't use `install`. Use a `.gyp` file for compilation, and | ||
| `prepublish` for anything else. | ||
|
|
||
| You should almost never have to explicitly set a `preinstall` or | ||
| `install` script. If you are doing this, please consider if there is | ||
| another option. | ||
|
|
||
| The only valid use of `install` or `preinstall` scripts is for | ||
| compilation which must be done on the target architecture. In early | ||
| versions of node, this was often done using the `node-waf` scripts, or | ||
| a standalone `Makefile`, and early versions of npm required that it be | ||
| explicitly set in package.json. This was not portable, and harder to | ||
| do properly. | ||
|
|
||
| In the current version of node, the standard way to do this is using a | ||
| `.gyp` file. If you have a file with a `.gyp` extension in the root | ||
| of your package, then npm will run the appropriate `node-gyp` commands | ||
| automatically at install time. This is the only officially supported | ||
| method for compiling binary addons, and does not require that you add | ||
| anything to your package.json file. | ||
|
|
||
| If you have to do other things before your package is used, in a way | ||
| that is not dependent on the operating system or architecture of the | ||
| target system, then use a `prepublish` script instead. This includes | ||
| tasks such as: | ||
|
|
||
| * Compile CoffeeScript source code into JavaScript. | ||
| * Create minified versions of JavaScript source code. | ||
| * Fetching remote resources that your package will use. | ||
|
|
||
| The advantage of doing these things at `prepublish` time instead of | ||
| `preinstall` or `install` time is that they can be done once, in a | ||
| single place, and thus greatly reduce complexity and variability. | ||
| Additionally, this means that: | ||
|
|
||
| * You can depend on `coffee-script` as a `devDependency`, and thus | ||
| your users don't need to have it installed. | ||
| * You don't need to include the minifiers in your package, reducing | ||
| the size for your users. | ||
| * You don't need to rely on your users having `curl` or `wget` or | ||
| other system tools on the target machines. | ||
|
|
||
| ## DEFAULT VALUES | ||
|
|
||
| npm will default some script values based on package contents. | ||
|
|
||
| * `"start": "node server.js"`: | ||
|
|
||
| If there is a `server.js` file in the root of your package, then npm | ||
| will default the `start` command to `node server.js`. | ||
|
|
||
| * `"preinstall": "node-waf clean || true; node-waf configure build"`: | ||
|
|
||
| If there is a `wscript` file in the root of your package, npm will | ||
| default the `preinstall` command to compile using node-waf. | ||
|
|
||
| ## 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. | ||
|
|
||
|
|
||
| ### path | ||
|
|
||
| If you depend on modules that define executable scripts, like test | ||
| suites, then those executables will be added to the `PATH` for | ||
| executing the scripts. So, if your package.json has this: | ||
|
|
||
| { "name" : "foo" | ||
| , "dependencies" : { "bar" : "0.1.x" } | ||
| , "scripts": { "start" : "bar ./test" } } | ||
|
|
||
| then you could run `npm start` to execute the `bar` script, which is | ||
| exported into the `node_modules/.bin` directory on `npm install`. | ||
|
|
||
| ### 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" | ||
| , "uninstall" : "scripts/uninstall.js" | ||
| } | ||
| } | ||
|
|
||
| then the `scripts/install.js` will be called for the install, | ||
| post-install, 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 | ||
|
|
||
| * Don't exit with a non-zero error code unless you *really* mean it. | ||
| Except for uninstall scripts, this will cause the npm action to | ||
| fail, and potentially be rolled back. If the failure is minor or | ||
| only will prevent some optional features, then it's better to just | ||
| print a warning and exit successfully. | ||
| * Try not to use scripts to do what npm can do for you. Read through | ||
| `package.json(5)` to see all the things that you can specify and enable | ||
| by simply describing your package appropriately. In general, this | ||
| will lead to a more robust and consistent state. | ||
| * Inspect the env to determine where to put things. For instance, if | ||
| the `npm_config_binroot` environ is set to `/home/user/bin`, then | ||
| don't try to install executables into `/usr/local/bin`. The user | ||
| probably set it up that way for a reason. | ||
| * Don't prefix your script commands with "sudo". If root permissions | ||
| are required for some reason, then it'll fail with that error, and | ||
| the user will sudo the npm command in question. | ||
|
|
||
| ## SEE ALSO | ||
|
|
||
| * npm-run-script(1) | ||
| * package.json(5) | ||
| * npm-developers(7) | ||
| * npm-install(1) |
| @@ -0,0 +1,142 @@ | ||
| semver(7) -- The semantic versioner for npm | ||
| =========================================== | ||
|
|
||
| ## Usage | ||
|
|
||
| $ npm install semver | ||
|
|
||
| semver.valid('1.2.3') // '1.2.3' | ||
| semver.valid('a.b.c') // null | ||
| 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: | ||
|
|
||
| $ semver -h | ||
|
|
||
| Usage: semver <version> [<version> [...]] [-r <range> | -i <inc> | -d <dec>] | ||
| Test if version(s) satisfy the supplied range(s), and sort them. | ||
|
|
||
| Multiple versions or ranges may be supplied, unless increment | ||
| or decrement options are specified. In that case, only a single | ||
| version may be used, and it is incremented by the specified level | ||
|
|
||
| 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 described by the v2.0.0 specification found at | ||
| <http://semver.org/>. | ||
|
|
||
| A leading `"="` or `"v"` character is stripped off and ignored. | ||
|
|
||
| ## Ranges | ||
|
|
||
| The following range styles are supported: | ||
|
|
||
| * `1.2.3` A specific version. When nothing else will do. Note that | ||
| build metadata is still ignored, so `1.2.3+build2012` will satisfy | ||
| this range. | ||
| * `>1.2.3` Greater than a specific version. | ||
| * `<1.2.3` Less than a specific version. If there is no prerelease | ||
| tag on the version range, then no prerelease version will be allowed | ||
| either, even though these are technically "less than". | ||
| * `>=1.2.3` Greater than or equal to. Note that prerelease versions | ||
| are NOT equal to their "normal" equivalents, so `1.2.3-beta` will | ||
| not satisfy this range, but `2.3.0-beta` will. | ||
| * `<=1.2.3` Less than or equal to. In this case, prerelease versions | ||
| ARE allowed, so `1.2.3-beta` would satisfy. | ||
| * `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4` | ||
| * `~1.2.3` := `>=1.2.3-0 <1.3.0-0` "Reasonably close to 1.2.3". When | ||
| using tilde operators, prerelease versions are supported as well, | ||
| but a prerelease of the next significant digit will NOT be | ||
| satisfactory, so `1.3.0-beta` will not satisfy `~1.2.3`. | ||
| * `^1.2.3` := `>=1.2.3-0 <2.0.0-0` "Compatible with 1.2.3". When | ||
| using caret operators, anything from the specified version (including | ||
| prerelease) will be supported up to, but not including, the next | ||
| major version (or its prereleases). `1.5.1` will satisfy `^1.2.3`, | ||
| while `1.2.2` and `2.0.0-beta` will not. | ||
| * `^0.1.3` := `>=0.1.3-0 <0.2.0-0` "Compatible with 0.1.3". 0.x.x versions are | ||
| special: the first non-zero component indicates potentially breaking changes, | ||
| meaning the caret operator matches any version with the same first non-zero | ||
| component starting at the specified version. | ||
| * `^0.0.2` := `=0.0.2` "Only the version 0.0.2 is considered compatible" | ||
| * `~1.2` := `>=1.2.0-0 <1.3.0-0` "Any version starting with 1.2" | ||
| * `^1.2` := `>=1.2.0-0 <2.0.0-0` "Any version compatible with 1.2" | ||
| * `1.2.x` := `>=1.2.0-0 <1.3.0-0` "Any version starting with 1.2" | ||
| * `~1` := `>=1.0.0-0 <2.0.0-0` "Any version starting with 1" | ||
| * `^1` := `>=1.0.0-0 <2.0.0-0` "Any version compatible with 1" | ||
| * `1.x` := `>=1.0.0-0 <2.0.0-0` "Any version starting with 1" | ||
|
|
||
|
|
||
| Ranges can be joined with either a space (which implies "and") or a | ||
| `||` (which implies "or"). | ||
|
|
||
| ## Functions | ||
|
|
||
| All methods and classes take a final `loose` boolean argument that, if | ||
| true, will be more forgiving about not-quite-valid semver strings. | ||
| The resulting output will always be 100% strict, of course. | ||
|
|
||
| Strict-mode Comparators and Ranges will be strict about the SemVer | ||
| strings that they parse. | ||
|
|
||
| * valid(v): Return the parsed version, or null if it's not valid. | ||
| * inc(v, release): Return the version incremented by the release type | ||
| (major, minor, patch, or prerelease), or null if it's not valid. | ||
|
|
||
| ### Comparison | ||
|
|
||
| * gt(v1, v2): `v1 > v2` | ||
| * gte(v1, v2): `v1 >= v2` | ||
| * lt(v1, v2): `v1 < v2` | ||
| * lte(v1, v2): `v1 <= v2` | ||
| * eq(v1, v2): `v1 == v2` This is true if they're logically equivalent, | ||
| even if they're not the exact same string. You already know how to | ||
| compare strings. | ||
| * neq(v1, v2): `v1 != v2` The opposite of eq. | ||
| * cmp(v1, comparator, v2): Pass in a comparison string, and it'll call | ||
| the corresponding function above. `"==="` and `"!=="` do simple | ||
| string comparison, but are included for completeness. Throws if an | ||
| invalid comparison string is provided. | ||
| * compare(v1, v2): Return 0 if v1 == v2, or 1 if v1 is greater, or -1 if | ||
| v2 is greater. Sorts in ascending order if passed to Array.sort(). | ||
| * rcompare(v1, v2): The reverse of compare. Sorts an array of versions | ||
| in descending order when passed to Array.sort(). | ||
|
|
||
|
|
||
| ### Ranges | ||
|
|
||
| * validRange(range): Return the valid range or null if it's not valid | ||
| * satisfies(version, range): Return true if the version satisfies the | ||
| range. | ||
| * maxSatisfying(versions, range): Return the highest version in the list | ||
| that satisfies the range, or null if none of them do. | ||
| * gtr(version, range): Return true if version is greater than all the | ||
| versions possible in the range. | ||
| * ltr(version, range): Return true if version is less than all the | ||
| versions possible in the range. | ||
| * outside(version, range, hilo): Return true if the version is outside | ||
| the bounds of the range in either the high or low direction. The | ||
| `hilo` argument must be either the string `'>'` or `'<'`. (This is | ||
| the function called by `gtr` and `ltr`.) | ||
|
|
||
| Note that, since ranges may be non-contiguous, a version might not be | ||
| greater than a range, less than a range, *or* satisfy a range! For | ||
| example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9` | ||
| until `2.0.0`, so the version `1.2.10` would not be greater than the | ||
| range (because 2.0.1 satisfies, which is higher), nor less than the | ||
| range (since 1.2.8 satisfies, which is lower), and it also does not | ||
| satisfy the range. | ||
|
|
||
| If you want to know if a version satisfies or does not satisfy a | ||
| range, use the `satisfies(version, range)` function. |