npmjs.com.cn

All Docs

What is npm?

npm makes it easy for JavaScript developers to share and reuse code, and it makes it easy to update the code that you're sharing.

If you've been working with Javascript for a while, you might have heard of npm: npm makes it easy for Javascript developers to share the code that they've created to solve particular problems, and for other developers to reuse that code in their own applications.

Once you're depending on this code from other developers, npm makes it really easy to check to see if they've made any updates to it, and to download those updates when they're made.

These bits of reusable code are called packages, or sometimes modules. A package is just a directory with one or more files in it, that also has a file called "package.json" with some metadata about this package. A typical application, such as a website, will depend on dozens or hundreds of packages. These packages are often small. The general idea is that you create a small building block which solves one problem and solves it well. This makes it possible for you to compose larger, custom solutions out of these small, shared building blocks.

There's lots of benefits to this. It makes it possible for your team to draw on expertise outside of your organization by bringing in packages from people who have focused on particular problem areas. But even if you don't reuse code from people outside of your organization, using this kind of module based approach can actually help your team work together better, and can also make it possible to reuse code across projects.

You can find packages to help you build your application by browsing the npm website. When you're browsing the website, you'll find different kinds of packages. You'll find lots of node modules. npm started as the node package manager, so you'll find lots of modules which can be used on the server side. There are also lots of packages which add commands for you to use in the command line. And at this point you can find a number of packages which can be used in the browser, on the front end.

So now that you have an idea of what npm can do, let's talk about how it works. When people talk about npm, they can be talking about one of three things. They could be talking about the website, which we've just been looking at. Or they could be talking about the registry, which is a big database of information about packages that people are sharing. Or the third thing they could be talking about is the client: when a developer decides to share their code, they use the npm client which is installed on their computer to publish that code up to the registry. And once there's an entry for this package in the registry, then other developers can use their npm clients to install the package from the registry. The entry in the registry for this package is also reflected on the website, where there's a page dedicated to this new package.

So that's what npm is. It's a way to reuse code from other developers, and also a way to share your code with them, and it makes it easy to manage the different versions of code.

Last modified February 11, 2017           Found a typo? Send a pull request!

Installing Node.js and updating npm

If you're using OS X or Windows, the best way to install Node.js is to use one of the installers from the Node.js download page. If you're using Linux, you can use the installer, or you can check NodeSource's binary distributions to see whether or not there's a more recent version that works with your system.

Test: Run node -v. The version should be higher than v0.10.32.

Node comes with npm installed so you should have a version of npm. However, npm gets updated more frequently than Node does, so you'll want to make sure it's the latest version.

npm install npm@latest -g

Test: Run npm -v. The version should be higher than 2.1.8.

For more advanced users.

The npm module is available for download at https://registry.npmjs.org/npm/-/npm-{VERSION}.tgz.

Last modified February 11, 2017           Found a typo? Send a pull request!

Fixing npm permissions

You may receive an EACCES error when you try to install a package globally. This indicates that you do not have permission to write to the directories that npm uses to store global packages and commands.

You can fix this problem using one of three options:

  1. Change the permission to npm's default directory.
  2. Change npm's default directory to another directory.
  3. Install node with a package manager that takes care of this for you.

You should back-up your computer before moving forward.

  1. Find the path to npm's directory:

     npm config get prefix
    

    For many systems, this will be /usr/local.

    WARNING: If the displayed path is just /usr, switch to Option 2 or you will mess up your permissions.

  2. Change the owner of npm's directories to the name of the current user (your username!):

     sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
    

    This changes the permissions of the sub-folders used by npm and some other tools (lib/node_modules, bin, and share).

There are times when you do not want to change ownership of the default directory that npm uses (i.e. /usr) as this could cause some problems, for example if you are sharing the system with other users.

Instead, you can configure npm to use a different directory altogether. In our case, this will be a hidden directory in our home folder.

  1. Make a directory for global installations:

     mkdir ~/.npm-global
    
  2. Configure npm to use the new directory path:

     npm config set prefix '~/.npm-global'
    
  3. Open or create a ~/.profile file and add this line:

     export PATH=~/.npm-global/bin:$PATH
    
  4. Back on the command line, update your system variables:

     source ~/.profile
    

Test: Download a package globally without using sudo.

    npm install -g jshint

Instead of steps 2-4 you can also use the corresponding ENV variable (e.g. if you don't want to modify ~/.profile):

    NPM_CONFIG_PREFIX=~/.npm-global

If you're doing a fresh install of node on Mac OS you can avoid this problem altogether by using the Homebrew package manager. Homebrew sets things up out of the box with the correct permissions.

brew install node

Last modified February 11, 2017           Found a typo? Send a pull request!

Installing npm packages locally

There are two ways to install npm packages: locally or globally. You choose which kind of installation to use based on how you want to use the package.

If you want to depend on the package from your own module using something like Node.js' require, then you want to install locally, which is npm install's default behavior. On the other hand, if you want to use it as a command line tool, something like the grunt CLI, then you want to install it globally.

To learn more about the install command's behavior, check out the CLI doc page.

A package can be downloaded with the command

> npm install <package_name>

This will create the node_modules directory in your current directory(if one doesn't exist yet), and will download the package to that directory.

To confirm that npm install worked correctly, check to see that a node_modules directory exists and that it contains a directory for the package(s) you installed. You can do this by running ls node_modules on Unix systems, e.g. "OSX", "Debian", or dir node_modules on Windows.

Install a package called lodash. Confirm that it ran successfully by listing the contents of the node_modules directory and seeing a directory called lodash.

> npm install lodash
> ls node_modules               # use `dir` for Windows
 
#=> lodash

If there is no package.json file in the local directory, the latest version of the package is installed.

If there is package.json file, the latest version satisfying the semver rule declared in package.json for that package (if there is any) is installed.

Once the package is in node_modules, you can use it in your code. For example, if you are creating a Node.js module, you can require it.

Create a file named index.js, with the following code:

// index.js 
var lodash = require('lodash');
 
var output = lodash.without([1, 2, 3], 1);
console.log(output);

Run the code using node index.js. It should output [2, 3].

If you had not properly installed lodash, you would receive this error:

module.js:340
    throw err;
          ^
Error: Cannot find module 'lodash'

To fix this, run npm install lodash in the same directory as your index.js.

Last modified February 11, 2017           Found a typo? Send a pull request!

Using a package.json

The best way to manage locally installed npm packages is to create a package.json file.

A package.json file affords you a lot of great things:

  1. It serves as documentation for what packages your project depends on.
  2. It allows you to specify the versions of a package that your project can use using semantic versioning rules.
  3. Makes your build reproducable which means that its way easier to share with other developers.

As a bare minimum, a package.json must have:

For example:

{
  "name": "my-awesome-package",
  "version": "1.0.0"
}

To create a package.json run:

> npm init

This will initate a command line questionnaire that will conclude with the creation of a package.json in the directory you initiated the command.

The extended CLI Q&A experience is not for everyone, and often if you are comfortable with using a package.json you'd like a more expedited experience.

You can get a default package.json by running npm init with the --yes or -y flag:

> npm init --yes

This will ask you only one question, author. Otherwise it will fill in default values:

> npm init --yes
Wrote to /home/ag_dubs/my_package/package.json:
 
{
  "name": "my_package",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "ag_dubs",
  "license": "ISC",
  "repository": {
    "type": "git",
    "url": "https://github.com/ashleygwilliams/my_package.git"
  },
  "bugs": {
    "url": "https://github.com/ashleygwilliams/my_package/issues"
  },
  "homepage": "https://github.com/ashleygwilliams/my_package"
}

You can also set several config options for the init command. Some useful ones:

> npm set init.author.email "wombat@npmjs.com"
> npm set init.author.name "ag_dubs"
> npm set init.license "MIT"

If there is no description field in the package.json, npm uses the first line of the README.md or README instead. The description helps people find your package on npm search, so it's definitely useful to make a custom description in the package.json to make your package more discoverable.

It is also possible to totally customize the information created and the questions asked during the init process. This is done by creating a custom .npm-init.js. By default, npm will look in your home directory. ~/.npm-init.js

A simple .npm-init.js could look something like this:

module.exports = {
  customField: 'Custom Field',
  otherCustomField: 'This field is really cool'
}

Running npm init with this file in your home directory, would output a package.json similiar to this:

{
  customField: 'Custom Field',
  otherCustomField: 'This field is really cool'
}

Customizing the questions is also possible, by using the prompt function.

  module.exports = prompt("what's your favorite flavor of ice cream buddy?", "I LIKE THEM ALL");

To learn more on how to create more advanced customizations, checkout the docs for init-package-json

To specify the packages your project depends on, you need to list the packages you'd like to use in your package.json file. There are 2 types of packages you can list:

You can manually edit your package.json. You'll need to create an attribute in the package object called dependencies that points to an object. This object will hold attributes named after the packages you'd like to use, that point to a semver expression that specifies what versions of that project are compatible with your project.

If you have dependencies you only need to use during local development, you will follow the same instructions as above but in an attribute called devDependencies.

For example: The project below uses any version of the package my_dep that matches major version 1 in production, and requires any version of the package my_test_framework that matches major version 3, but only for development:

{
  "name": "my_package",
  "version": "1.0.0",
  "dependencies": {
    "my_dep": "^1.0.0"
  },
  "devDependencies" : {
    "my_test_framework": "^3.1.0"
  }
}

The easier (and more awesome) way to add dependencies to your package.json is to do so from the command line, flagging the npm install command with either --save or --save-dev, depending on how you'd like to use that dependency.

To add an entry to your package.json's dependencies:

npm install <package_name> --save

To add an entry to your package.json's devDependencies:

npm install <package_name> --save-dev

npm uses Semantic Versioning, or, as we often refer to it, SemVer, to manage versions and ranges of versions of packages.

If you have a package.json file in your directory and you run npm install, then npm will look at the dependencies that are listed in that file and download the latest versions satisfying semver rules for all of those.

To learn more about semantic versioning, check out our Getting Started "Semver" page.

Last modified February 11, 2017           Found a typo? Send a pull request!

Updating local packages

Every so often, you should update the packages you depend on so you can get any changes that have been made to code upstream.

To do this, run npm update in the same directory as your package.json file.

Test: Run npm outdated. There should not be any results.

Last modified February 11, 2017           Found a typo? Send a pull request!

Uninstalling local packages

You can remove a package from your node_modules directory using npm uninstall <package>:

npm uninstall lodash

To remove it from the dependencies in package.json, you will need to use the save flag:

npm uninstall --save lodash

Note: if you installed the package as a "devDependency" (i.e. with --save-dev) then --save won't remove it from package.json You have to use --save-dev to uninstall it.

To confirm that npm uninstall worked correctly, check to see that the node_modules directory exists, but that it does not contain a directory for the package(s) you uninstalled. You can do this by running ls node_modules on Unix systems, e.g. "OSX", "Debian", or dir node_modules on Windows.

Install a package called lodash. Confirm that it ran successfully by listing the contents of the node_modules directory and seeing a directory called lodash.

Uninstall lodash with npm uninstall. Confirm that it ran successfully by listing the contents of the node_modules directory and confirming the absence of a directory called lodash.

> npm install lodash
> ls node_modules               # use `dir` for Windows
 
#=> lodash
 
> npm uninstall lodash
> ls node_modules
 
#=>

Last modified February 11, 2017           Found a typo? Send a pull request!

Installing npm packages globally

There are two ways to install npm packages: locally or globally. You choose which kind of installation to use based on how you want to use the package.

If you want to use it as a command line tool, something like the grunt CLI, then you want to install it globally. On the other hand, if you want to depend on the package from your own module using something like Node's require, then you want to install locally.

To download packages globally, you simply use the command npm install -g <package>, e.g.:

npm install -g jshint

If you get an EACCES error, you should fix your permissions. You could also try using sudo, but this should be avoided:

sudo npm install -g jshint

Last modified February 11, 2017           Found a typo? Send a pull request!

Updating global packages

To update global packages, you can use npm update -g <package>:

npm update -g jshint

To find out which packages need to be updated, you can use npm outdated -g --depth=0.

To update all global packages, you can use npm update -g. However, for npm versions less than 2.6.1, this script is recommended to update all outdated global packages.

Last modified February 11, 2017           Found a typo? Send a pull request!

Uninstalling global packages

Global packages can be uninstalled with npm uninstall -g <package>:

npm uninstall -g jshint

Last modified February 11, 2017           Found a typo? Send a pull request!

Creating Node.js modules

Node.js modules are one kind of package which can be published to npm. When you create a new module, you want to start with the package.json file.

You can use npm init to create the package.json. It will prompt you for values for the package.json fields. The two required fields are name and version. You'll also want to have a value for main. You can use the default, index.js.

If you want to add information for the author field, you can use the following format (email and web site are both optional):

Your Name <email@example.com> (http://example.com)

Once your package.json file is created, you'll want to create the file that will be loaded when your module is required. If you used the default, this is index.js.

In that file, add a function as a property of the exports object. This will make the function available to other code.

exports.printMsg = function() {
  console.log("This is a message from the demo package");
}

Test:

  1. Publish your package to npm
  2. Make a new directory outside of your project and cd into it
  3. Run npm install <package>
  4. Create a test.js file which requires the package and calls the method
  5. Run node test.js. The message should be output.

Last modified February 11, 2017           Found a typo? Send a pull request!

Publishing npm packages

You can publish any directory that has a package.json file, e.g. a node module.

To publish, you must have a user on the npm registry. If you don't have one, create it with npm adduser. If you created one on the site, use npm login to store the credentials on the client.

Test: Use npm config ls to ensure that the credentials are stored on your client. Check that it has been added to the registry by going to https://npmjs.com/~.

Use npm publish to publish the package.

Note that everything in the directory will be included unless it is ignored by a local .gitignore or .npmignore file as described in npm-developers.

Also make sure there isn't already a package with the same name, owned by somebody else.

Test: Go to https://npmjs.com/package/<package>. You should see the information for your new package.

When you make changes, you can update the package using npm version <update_type>, where update_type is one of the semantic versioning release types, patch, minor, or major. This command will change the version number in package.json. Note that this will also add a tag with this release number to your git repository if you have one.

After updating the version number, you can npm publish again.

Test: Go to https://npmjs.com/package/<package>. The package number should be updated.

The README displayed on the site will not be updated unless a new version of your package is published, so you would need to run npm version patch and npm publish to have a documentation fix displayed on the site.

Last modified February 11, 2017           Found a typo? Send a pull request!

Semantic versioning and npm

Semantic versioning is a standard that a lot of projects use to communicate what kinds of changes are in this release. It's important to communicate what kinds of changes are in a release because sometimes those changes will break the code that depends on the package.

If a project is going to be shared with others, it should start at 1.0.0, though some projects on npm don't follow this rule.

After this, changes should be handled as follows:

As a consumer, you can specify which kinds of updates your app can accept in the package.json file.

If you were starting with a package 1.0.4, this is how you would specify the ranges:

You can also specify more granular semver ranges.

Last modified February 11, 2017           Found a typo? Send a pull request!

Working with scoped packages

Scopes are like namespaces for npm modules. If a package's name begins with @, then it is a scoped package. The scope is everything in between the @ and the slash.

@scope/project-name

Each npm user has their own scope.

@username/project-name

You can find more in depth information about scopes in the CLI documentation.

You need a version of npm greater than 2.7.0, and you'll need to log in to npm again on the command line if this is your first time using scoped modules.

sudo npm install -g npm
npm login

To create a scoped package, you simply use a package name that starts with your scope.

{
  "name": "@username/project-name"
}

If you use npm init, you can add your scope as an option to that command.

npm init --scope=username

If you use the same scope all the time, you will probably want to set this option in your .npmrc file.

npm config set scope username

Scoped packages are private by default. To publish private modules, you need to be a paid private modules user.

However, public scoped modules are free and don't require a paid subscription. To publish a public scoped module, set the access option when publishing it. This option will remain set for all subsequent publishes.

npm publish --access=public

To use a scoped package, you simply include the scope wherever you use the package name.

In package.json:

{
  "dependencies": {
    "@username/project-name": "^1.0.0"
  }
}

On the command line:

npm install @username/project-name --save

In a require statement:

var projectName = require("@username/project-name")

For information about using scoped private modules, visit npmjs.com/private-modules.

Last modified February 11, 2017           Found a typo? Send a pull request!

Using dist-tags

Tags are a supplement to semver (e.g., v0.12) for organizing and labeling different versions of packages. In addition to being more human-readable, tags allow publishers to distribute their packages more effectively.

To add a tag to a specific version of your package, use npm dist-tag add <pkg>@<version> [<tag>]. See the CLI docs for more information.

By default, npm publish will tag your package with the latest tag. If you use the --tag flag, you can specify another tag to use. For example, the following will publish your package with the beta tag:

npm publish --tag beta

Like npm publish, npm install <pkg> will use the latest tag by default. To override this behavior, use npm install <pkg>@<tag>. The following example will install the somepkg at the version that has been tagged with beta.

npm install somepkg@beta

Because dist-tags share the same namespace with semver, avoid using any tag names that may cause a conflict. The best practice is to avoid using tags beginning with a number or the letter "v".

Last modified February 11, 2017           Found a typo? Send a pull request!

Packages and Modules

One of the key steps in becoming immersed in an ecosystem is learning its vocabulary. Node.js and npm have very specific definitions of packages and modules, which are easy to mix up. We'll discuss those definitions here, make them distinct, and explain why certain default files are named the way they are.

A package is any of the following:

Noting all these package possibilities, it follows that even if you never publish your package to the public registry, you can still get a lot of benefits of using npm:

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.

A module is anything that can be loaded with require() in a Node.js program. The following are all examples of things that can be loaded as modules:

Generally, npm packages that are used in Node.js program are loaded with require, making them modules. However, there's no requirement that an npm package be a module!

Some packages, e.g., cli packages, only contain an executable command-line interface and don't provide a main field for use in Node.js programs. These packages are not modules.

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

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'), 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().

Last modified February 11, 2017           Found a typo? Send a pull request!

npm v2 Dependency Resolution

Imagine there are three modules: A, B, and C. A requires B at v1.0, and C also requires B, but at v2.0. We can visualize this like so:

2 modules need B

Now, let's create an application that requires both module A and module C.

My app needs both A and C

A package manager would need to provide a version of module B. In all other runtimes prior to Node.js, this is what a package manager would try to do. This is dependency hell:

Dependency Hell

Instead of attempting to resolve module B to a single version, npm puts both versions of module B into the tree, each version nested under the module that requires it.

what npm does

In the terminal, this looks like this:

tree

You can list the dependencies and still see their relationships using npm ls:

npmls

If you want to just see your primary dependencies, you can use:

npm ls --depth=0

npmlsdepth0

However, npm doing this is not enough. Despite the fact that their nested locations allow for the coexistence of two versions of the same module, most module loaders are unable to load two different versions of the same module into memory. Luckily, the Node.js module loader is written for exactly this situation, and can easily load both versions of the module in a way that they do not conflict with each other.

How is it that npm and the node module loader are so wonderfully symbiotic? They were both written in large part by the same person, npm, Inc. CEO, Isaac Z. Schlueter. Like 2 sides of the same piece of paper, npm and the Node.js module loader are what make Node.js a uniquely well-suited runtime for dependency management.

Last modified February 11, 2017           Found a typo? Send a pull request!

npm v3 Dependency Resolution

npm3 resolves dependencies differently than npm2.

While npm2 installs all dependencies in a nested way, npm3 tries to mitigate the deep trees and redundancy that such nesting causes. npm3 attempts this by installing some secondary dependencies (dependencies of dependencies) in a flat way, in the same directory as the primary dependency that requires it.

The key major differences are:

Imagine we have a module, A. A requires B.

A depends on B

Now, let's create an application that requires module A.

On npm install, npm v3 will install both module A and its dependency, module B, inside the /node_modules directory, flat.

In npm v2 this would have happened in a nested way.

npm2 vs 3

Now, let's say we want to require another module, C. C requires B, but at another version than A.

new module dep, C

However, since B v1.0 is already a top-level dep, we cannot install B v2.0 as a top level dependency. npm v3 handles this by defaulting to npm v2 behavior and nesting the new, different, module B version dependency under the module that requires it -- in this case, module C.

nested dep

In the terminal, this looks like this:

tree

You can list the dependencies and still see their relationships using npm ls:

npmls

If you want to just see your primary dependencies, you can use:

npm ls --depth=0

npmlsdepth0

Last modified February 11, 2017           Found a typo? Send a pull request!

npm3 Duplication and Deduplication

Let's continue with our example before. Currently we have an application that depends on 2 modules:

our app so far

Now we ask ourselves, what happens if we install another module that depends on Module B v1.0? or Module B v2.0?

Ok, so let's say we want to depend on another package, module D. Module D depends on Module B v2.0, just like Module C.

new module dep, D

Because B v1.0 is already a top-level dependency, we cannot install B v2.0 as a top level dependency. Therefore Module B v2.0 is installed as a nested dependency of Module D, even though we already have a copy installed, nested beneath Module C.

no dedupe

If a secondary dependency is required by 2+ modules, but was not installed as a top-level dependency in the directory hierarchy, it will be duplicated and nested beneath the primary dependency.

However, if a secondary dependency is required by 2+ modules, but is installed as a top-level dependency in the directory hierarchy, it will not be duplicated, and will be shared by the primary dependencies that require it.

For example, let's say we now want to depend on Module E. Module E, like Module A, depends on Module B v1.0.

new module dep, E

Because B v1.0 is already a top-level dependency, we do not need to duplicate and nest it. We simply install Module E and it shares Module B v1.0 with Module A.

dedupe

This appears like this in the terminal:

tree2

Now-- what happens if we update Module A to v2.0, which depends on Module B v2.0, not Module B v1.0?

bump Module A to version 2, deps on Bv2

The key is to remember that install order matters.

Even though Module A was installed first (as v1.0) via our package.json (because it is ordered alphabetically), using the interactive npm install command means that Module A v2.0 is the last package installed.

As a result, npm3 does the following things when we run npm install mod-a@2 --save:

bv1.0 stays even though a doesn't dep on it anymore

This looks like this in the terminal:

tree3

Finally, let's also update Module E to v2.0, which also depends on Module B v2.0 instead of Module B v1.0, just like the Module A update.

bump Module E to version 2, deps on Bv2

npm3 performs the following things:

now we have Bv2.0 everywhere

This looks like this in the terminal:

tree4

Now, this is clearly not ideal. We have Module B v2.0 in nearly every directory. To get rid of duplication, we can run:

npm dedupe

This command resolves all of the packages dependencies on Module B v2.0 by redirecting them to the top level copy of Module B v2.0 and removes all the nested copies.

deduped

This looks like this in the terminal:

tree5

Last modified February 11, 2017           Found a typo? Send a pull request!

npm3 Non-determinism

As stated a few pages back in our example:

install order

If you, and your development team, use a package.json, as well as the interactive npm install command to add pkgs (like most teams using npm do), it is likely that you will run into a situation where your local node_modules directory will differ from both your coworkers' node_modules directories, as well as the node_modules directories on your staging, testing, or production servers.

In short? npm3 does not install dependencies in a deterministic way.

That's probably not a comforting statement to read, but in this article we'll discuss why this happens, as well as assure you that it has no implications for your application, as well as explain the steps to reliably (re)create a single, consistent, node_modules directory, should you want to do that.

Let's jump back to an example application from a few examples ago:

app

In this example, our app has the following package.json:

{
  "name": "example3",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "mod-a": "^1.0.0",
    "mod-c": "^1.0.0",
    "mod-d": "^1.0.0",
    "mod-e": "^1.0.0"
  }
}

On an npm install we will see this in our terminal:

npm install

Now, let's say a developer on our team decides to complete a feature that requires that they update Module A to v2.0, which now has a dependency on Module B v2.0, instead of, as previously, Module B v1.0.

module a v2

Our developer uses the interactive npm install command to install the new version of Module A, and save it to the package.json:

npm install mod-a@2 --save

The terminal outputs this:

interactive install mod a

We now have something that looks like this:

tree with mod a v2 interactive

Now let's say that our developer finished the feature requiring the new version of Module A and pushes the application to a testing server that runs npm install on the new package.json:

{
  "name": "example3",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "mod-a": "^2.0.0",
    "mod-c": "^1.0.0",
    "mod-d": "^1.0.0",
    "mod-e": "^1.0.0"
  }
}

The testing server's log shows this:

tree with mod a v2 packagejson

Which, when visualized, looks like this:

totally diff dep tree

Whoa, what?! This tree is completely different than the tree that exists on our developer's local machine. What happened?

Remember: install order matters.

When our developer updated Module A using the interactive npm install Module A v2.0 was functionally the last package installed. Because our developer had done an npm install when they first started working on the project, all modules listed in the package.json were already installed in the node_modules folder. Then Module A v2.0 was installed.

It follows, then, that Module Bv1.0, a top level dependency because of Module A v1.0, then anchored by Module E v1.0, remains a top level dependency. Because Module Bv1.0 occupies the top-level, no other version of Module B can-- therefore, Module Bv2.0 remains a nested dependency under Module C v1.0 and Module D v1.0, and becomes a nested dependency for the new Module A v2.0 dependency.

Let's consider what happened on the testing server. The project was pulled into a fresh directory, i.e. does not have a pre-existing node_modules directory. Then npm install is run, perhaps by a deploy script, to install dependencies from the package.json.

This package.json now has Module A v2.0 listed in it, and thanks to alphabetical order (enforced by the npm install command), is now installed first, instead of last.

When Module A v2.0 is installed first, in a clear node_modules directory, its dependencies are the first candidates for the top-level position. As a result, Module B v2.0 is installed in the top-level of the node_modules directory.

Now, when it is time to install Module E v1.0, its dependency, Module B v1.0, cannot occupy the top-level of the node_modules directory, because Module B v2.0 is already there. Therefore, it is nested under Module E v1.0.

No! Even though the trees are different, both sufficiently install and point all your dependencies at all their dependencies, and so on, down the tree. You still have everything you need, it just happens to be in a different configuration.

The npm install command, when used exclusively to install packages from a package.json, will always produce the same tree. This is because install order from a package.json is always alphabetical. Same install order means that you will get the same tree.

You can reliably get the same dependency tree by removing your node_modules directory and running npm install whenever you make a change to your package.json.

Last modified February 11, 2017           Found a typo? Send a pull request!

Working with private modules

With npm private modules, you can use the npm registry to host your own private code and the npm command line to manage it. This makes it easy to use public modules like Express and Browserify side-by-side with your own private code.

You need a version of npm greater than 2.7.0, and you'll need to log in to npm again.

sudo npm install -g npm
npm login

All private packages are scoped.

Scopes are a new feature of npm. If a package's name begins with @, then it is a scoped package. The scope is everything in between the @ and the slash.

@scope/project-name

When you sign up for private modules as an individual user, your scope is your username.

@username/project-name

If you use npm init to initialize your packages, you can pass in your scope like this:

npm init --scope=<your_scope>

If you use the same scope most of the time, you'll probably want to set it in your default configuration instead.

npm config set scope <your_scope>

Publishing your package is easy.

npm publish

By default, scoped packages are published as private. You can read more about this in the scopes documentation.

Once it's published, you should see it on the website with a private flag.

If you want to give access to someone, they need to be subscribed to private modules as well. Once they are, you can give them read or read-write access.

You can control access to the package on the access page. To get to the page, click on the Collaborators link or the plus button.

Add collaborators by entering the username and hitting enter.

You can also add collaborators on the command line:

npm owner add <user> <package name>

To install a private module, you must have access to the package. Then you can use install with the scoped package name.

npm install @scope/project-name

You also use the scoped package name when requiring it.

var project = require('@scope/project-name')

All scoped packages default to private. This ensures that you don't make something public by accident. You can change this on the access page.

You can also manage package access via the command line:

npm access restricted <package_name>

The package will be removed from listings on the site within a few minutes of making it private.

Last modified February 11, 2017           Found a typo? Send a pull request!

Downloading modules to CI/deployment servers

If you are using deployment servers or testing with CI servers, you'll need a way to download your private modules to those servers. To do this, you can set up an .npmrc file which will authenticate your server with npm.

One of the things that has changed in npm is that we now use auth tokens to authenticate in the CLI. To generate an auth token, you can log in on any machine. You'll end up with a line in your .npmrc file that looks like this:

//registry.npmjs.org/:_authToken=00000000-0000-0000-0000-000000000000

The token is not derived from your password, but changing your password will invalidate all tokens. The token will be valid until the password is changed. You can also invalidate a single token by logging out on a machine that is logged in with that token.

To make this more secure when pushing it up to the server, you can set this token as an environment variable on the server. For example, in Heroku you would do this:

heroku config:set NPM_TOKEN=00000000-0000-0000-0000-000000000000 --app=application_name

You will also need to add this to your environment variables on your development machine. In OSX or Linux, you would add this line to your ~/.profile:

export NPM_TOKEN="00000000-0000-0000-0000-000000000000"

and then refresh your environment variables:

source ~/.profile

Then you can check in the .npmrc file, replacing your token with the environment variable.

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Last modified February 11, 2017           Found a typo? Send a pull request!

Docker and private modules

If you've read through Working with private modules, you'll know that in order to use private modules, you need to be logged in to npm via the npm CLI.

If you're using npm private modules in an environment where you're not directly able to log in, such as inside a CI Server or a Docker container, you'll need to get and export an npm token as an environment variable. That token should look like NPM_TOKEN=00000000-0000-0000-0000-000000000000.

The Getting an Authentication Token should help you generate that token.

If this is the workflow you need, please read the CI Server Config doc. If that works with your system then perfect.

If it doesn't, here we'll look at the problems with this workflow when running npm install inside a Docker container.

If you had the following Dockerfile:

FROM risingstack/alpine:3.3-v4.3.1-3.0.1
 
COPY package.json package.json  
RUN npm install
 
# Add your source files
COPY . .  
CMD npm start  

Which will use the RisingStack Alpine Node.JS Docker image, copy the package.json into our container, installs dependencies, copies the source files and runs the start command as specified in the package.json.

In order to install private packages, you may think that we could just add a line before we run npm install, using the ENV parameter:

ENV NPM_TOKEN=00000000-0000-0000-0000-000000000000

However this doesn't work as you would expect, because you want the npm install to occur when you run docker build, and in this instance, ENV variables aren't used, they are set for runtime only.

We have to take advantage of a different way of passing environment variables to Docker, available since Docker 1.9. We'll use the slightly confusingly named ARG parameter.

A complete example that will allow us to use --build-arg to pass in our NPM_TOKEN requires adding a .npmrc file to the project. That file should contain the following content:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

The Dockerfile that takes advantage of this has a few more lines in it than our example earlier that allows us to use the .npmrc file and the ARG parameter.

FROM risingstack/alpine:3.3-v4.3.1-3.0.1
 
ARG NPM_TOKEN  
COPY .npmrc .npmrc  
COPY package.json package.json  
RUN npm install  
RUN rm -f .npmrc
 
# Add your source files
COPY . .  
CMD npm start

This adds the expected ARG NPM_TOKEN, but also copies the .npmrc file, and removes it when npm install completes.

To build the image using this Dockerfile and the token, you can run the following (note the . at the end to give docker build the current directory as an argument):

docker build --build-arg NPM_TOKEN=${NPM_TOKEN} .

This will take your current NPM_TOKEN environment variable, and will build the docker image using it, so you can run npm install inside your container as the current logged in user!

Note: Even if you delete the .npmrc file, it'll be kept in the commit history - to clean your secret up entirely make sure to squash them.

Last modified February 11, 2017           Found a typo? Send a pull request!

What are Organizations?

npm Organizations allow you to manage and monitor access to both new and pre-existing public and private packages through the use of teams.

A great way to think about Organizations is that they are the umbrella structure that allows you to create teams and then grant package access to those teams.

These docs can be seen as being separated into 2 sections: people and packages.

Managing People (npm team)

Managing Package Access (npm access)

An Organization can collaborate on 2 types of packages:

Additionally, all team members have the ability to monitor access to packages.

For full documentation on the CLI commands associated with this feature:

Last modified February 11, 2017           Found a typo? Send a pull request!

Setting up an Organization

Organizations and Organization membership are created in the npm web interface.

In order to create an Organization, you must be logged in as a npm user with a verified email address. To create an npm user, click here. There are 2 ways to create an organization:

  1. Log in to http://www.npmjs.com/
  2. Visit https://www.npmjs.com/org/create
  3. Click the big red button "Create an Organization"

Once you've created an Organization, you can perform a wide variety of tasks on your Organization Dashboard.

Your Organization Dashboard is located:

https://www.npmjs.com/org/<org>

...where <org> is the name of your Organization.

By default, your Organization is set up with a developers team. Whenever you add a new member to your Organization, they are automatically added to the developers team.

You may delete the developers team. If you do, newly added Organization members will not be added to any teams by default.

For more information about the developers team, see Developers Team

To add a member to your organization, you add them by their npm username via the Organization Dashboard.

As the creator of the Organization you are granted the role of Super Admin.

For more information about the Super Admin and Team Admin roles, checkout the Roles documentation.

Many users have already registered an npm user with the @scope they want to use for their org. If you attempt to register an org with a scope already in use, and you are already logged in as that user, you will be prompted to automatically migrate that user to an org.

Once your @scope is owned by an org, you can no longer log in as your former username. Orgs are not users and do not have usernames and passwords. During migration, you will be prompted to pick a new username. This new user will have the same password as your old user, but all packages that belonged to your old user will now belong to the org. Your new user will have Super-Admin privileges to the org.

Last modified February 11, 2017           Found a typo? Send a pull request!

Roles

Organizations are first and foremost a way to manage access, roles and resposibilities. Organizations offer 3 types of roles, and also have an interface with the general public:

Last modified February 11, 2017           Found a typo? Send a pull request!

The Developers Team

When you first create an Organization, a team called developers is created.

The developers team is a special team. While it can be deleted if you so choose, by default it acts as a "catch-all" team. This means:

The effects of deleting the team are covered below.

You may delete the developers team. If you do, newly added Organization members will not be added to any teams by default. Additionally, you will not be able to see all users in your org from the CLI, as one can only view the members of a team via the CLI.

You should also note that upon publish, in the absence of a developers team, it is difficult to determine who should be set as maintainers of that package. npm will do its best to fallback to another Organization team that the publisher is a member of. This is not predictable.

If you've removed the developers team, but now want it back, you can reinstate it by creating a new team called developers (case sensitive!). You will need to add all current members of the Organization to the new developers team, but, going forward all newly added Organization members will be automatically added to the new developers team.

Last modified February 11, 2017           Found a typo? Send a pull request!

Teams

The key to managing access to packages via Organizations is Teams.

Teams are sets of users that have access to a certain scope within the Organization.

In order to create teams and manage team membership, you must be a Super Admin or Team Admin under the given organization. Listing teams and team memberships may be done by any member of the organization.

Organization creation and management of Team Admin and Team Member roles is done through the web interface.

A Super Admin or Team Admin has the ability to create a team. To create a team one can type:

> npm team create <org:team>

...where <org:team> is the name of the Organization, followed by the name of the new team.

For example, to create a team called wombats in the @npminc Organization, a Super Admin or Team Admin would type:

> npm team create npminc:wombats

You can check that you created the team successfully by listing the teams in your Organization. You can do that by typing:

> npm team ls <org>

or by visiting the Organization Dashboard in the web interface.

Once you've created a team you'll want to add users to it. To do so a Super Admin or Team Admin can type:

> npm team add <org:team> <user>

...where org:team is the name of the Organization, followed by the name of the team and is the npm username of the user you'd like to make a member of the team.

For example, to make the npm user ag_dubs a member of the @npminc organization's wombats team:

> npm team add npminc:wombats ag_dubs

To check if you've added a user successfully, you can list all the users on a particular team. To do so, type:

> npm team ls <org:team>
> npm team rm <org:team> <user>
> npm team ls <org>
> npm team ls <org:team>

For detailed information on the team command, check out the CLI documentation here.

Last modified February 11, 2017           Found a typo? Send a pull request!

Sponsorship

org-sponsorship levels

Let's say we have an Organization, @ag_org. This Organization was created by user @ag_dubs, and therefore she is the Super Admin.

super admin

Being a Super Admin, she adds 3 members to her team:

There are three types of Sponsorship that can occur:

When Super Admin, @ag_dubs, added JacquesDerrida to the Organization, JacquesDerrida did not already belong to an organization nor did they have a subscription to private packages.

By default, when the Super Admin added him to the Organization, JacquesDerrida was set as a member of the Organization, paid by the current organization. This appears in the UI like this:

paid by current org

JacquesDerrida cannot:

Last modified February 11, 2017           Found a typo? Send a pull request!

Scoping a Package to your Organization

Once you have an Organization set up, you'll want to scope packages to that Organization.

Users with Super Admin, Team Admin, and Member roles can perform this action.

To do this, run these commands in the root directory of your package:

> npm init --scope=<org>
> npm publish

... where <org> is the name of your Organization.

If you are using Organizations, there is a good chance that you'll be using the Organization scope regularly.

To save yourself some typing, you can set your Organization as your default scope:

npm config set scope <org>

... where <org> is the name of your Organization.

Last modified February 11, 2017           Found a typo? Send a pull request!

Managing Organization Package Access

Once you have scoped a package to your Organization, users with Super Admin or Team Admin roles in your Organization can grant, revoke, and monitor team access to that package.

There are two levels of access you can provide:

To grant access to a team, a Team Admin can type:

> npm access grant <read-only|read-write> <org:team> [<package>]

The grant command takes 3 arguments, in order:

For example, to grant read-write access the npm-docs package to the @npminc org's wombats team, a user who:

...would do the following:

> npm access grant read-write npminc:wombats npm-docs

To revoke team access to a package, a Team Admin can type:

> npm access revoke <org:team> [<package>]

Again, the package argument is optional if this command is executed in a directory containing a package.json.

You can check whether you have successfully granted or revoked team access to a package using the npm access ls-packages and npm access ls-collaborators command.

npm access ls-packages <org> <user>
npm access ls-packages <org:team>
npm access ls-collaborators <pkg>

Last modified February 11, 2017           Found a typo? Send a pull request!

Manage Team Access To Previously Existing Packages

Currently, it is not possible to change the scope of a pre-existing public or private, scoped or not, package to an Organization.

Specifically, given a private, scoped package @ag_dubs/foo, there is currently no way to make that exact package scoped to the Organization, @ag_org, i.e. @ag_org/foo without creating a new package.

However, Organization members who are either a

that are also:

and, as of npm@3.5.0/npm@2.14.12:

... are able to grant Organization team access to packages that are not scoped within the Organization.

(*yup. this is weird. we know.)

Note: It is possible to migrate a User scope to an Organization scope. For more information on that check out the Migrating a Current User Scope to an Org in the Creating an Org documentation.

So, let's say you have a package @ag_dubs/foo that you would like to collaborate on within the Organization @ag_org.

First, ensure that you have the correct permissions. The user must:

Then, you can grant team access to a package, as though it were scoped to the Organization:

> > npm access grant <read-only|read-write> <org:team> @ag_dubs/foo

Last modified February 11, 2017           Found a typo? Send a pull request!

npm-coding-style

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 that you can download from the npm registry.

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.

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 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()
}

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.

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

Use single quotes for strings except to avoid escaping.

Bad:

var notOk = "Just double quotes"

Good:

var ok = 'String contains "double" quotes'
var alsoOk = "String contains 'single' quotes or apostrophe"

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.

Use named functions. They make stack traces a lot easier to read.

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.

Always create a new Error object with your message. Don't just return a string message to the callback. Stack traces are handy.

Logging is done using the 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 and search for "loglevel".

Use lowerCamelCase for multiword identifiers when they refer to objects, functions, methods, properties, 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.

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.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-config

npm gets its configuration values from the following sources, sorted by priority:

Putting --foo bar on the command line sets the foo configuration parameter to "bar". A -- argument tells the cli parser to stop reading flags. A --flag parameter that is at the end of the command will be given the value of true.

Any environment variables that start with npm_config_ will be interpreted as a configuration parameter. For example, putting npm_config_foo=bar in your environment will set the foo configuration parameter to bar. Any environment configurations that are not given a value will be given the value of true. Config values are case-insensitive, so NPM_CONFIG_FOO=bar will work the same. However, please note that inside npm-scripts npm will set it's own environment variables and Node will prefer those lowercase versions over any uppercase ones that you might set. For details see this issue.

The four relevant files are:

See npmrc for more details.

Run npm config ls -l to see a set of configuration parameters that are internal to npm, and are defaults if nothing else is specified.

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

When running scripts (see npm-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

See package.json for more information.

When publishing scoped packages, the access level defaults to restricted. If you want your scoped package to be publicly viewable (and installable) set --access=public. The only valid values for access are public and restricted. Unscoped packages always have an access level of public.

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

When "dev" or "development" and running local npm shrinkwrap, npm outdated, or npm update, is an alias for --dev.

Tells npm to create symlinks (or .cmd shims on Windows) for package executables.

Set to false to have it not do this. This can be used to work around the fact that some file systems don't support symlinks, even on ostensibly Unix systems.

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

The Certificate Authority signing certificate that is trusted for SSL connections to the registry. Values should be in PEM format with newlines replaced by the string "\n". For example:

ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

Set to null to only allow "known" registrars, or to a specific CA cert to trust only that specific signing authority.

Multiple CAs can be trusted by specifying an array of certificates:

ca[]="..."
ca[]="..."

See also the strict-ssl config.

A path to a file containing one or multiple Certificate Authority signing certificates. Similar to the ca setting, but allows for multiple CA's, as well as for the CA information to be stored in a file on disk.

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

The number of ms before cache folder lockfiles are considered stale.

Number of times to retry to acquire a lock on cache folder lockfiles.

Number of ms to wait for cache lock files to expire.

The maximum time (in seconds) to keep items in the registry cache before re-checking against the registry.

Note that no purging is done unless the npm cache clean command is explicitly used, and that only GET requests use the cache.

The minimum time (in seconds) to keep items in the registry cache before re-checking against the registry.

Note that no purging is done unless the npm cache clean command is explicitly used, and that only GET requests use the cache.

A client certificate to pass when accessing the registry. Values should be in PEM format with newlines replaced by the string "\n". For example:

cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

It is not the path to a certificate file (and there is no "certfile" option).

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

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

For npm outdated, a setting of Infinity will be treated as 0 since that gives more useful information. To show the outdated status of all packages and dependents, use a large integer value, e.g., npm outdated --depth 9999

Show the description in npm search

Install dev-dependencies along with packages.

Indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, install, update, dedupe, uninstall. This is NOT currently honored by network related commands, eg dist-tags, owner, publish, etc.

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

If set to true, then npm will stubbornly refuse to install (or even consider installing) any package that claims to not be compatible with the current Node.js version.

Makes various commands more forceful.

The "retries" config for the retry module to use when fetching packages from the registry.

The "factor" config for the retry module to use when fetching packages.

The "minTimeout" config for the retry module to use when fetching packages.

The "maxTimeout" config for the retry module to use when fetching packages.

The command to use for git commands. If git is installed on the computer, but is not in the PATH, then set this to the full path to the git binary.

Tag the commit when using the npm version command.

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

The config file to read for global config options.

Causes npm to install the package into your local node_modules folder with the same layout it uses with the global node_modules folder. Only your direct dependencies will show in node_modules and everything they depend on will be flattened in their node_modules folders. This obviously will eliminate some deduping. If used with legacy-bundling, legacy-bundling will be preferred.

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

The string that starts all the debugging log output.

A proxy to use for outgoing https requests. If the HTTPS_PROXY or https_proxy or HTTP_PROXY or http_proxy environment variables are set, proxy settings will be honored by the underlying request library.

If true, npm will not exit with an error code when run-script is invoked for a script that isn't defined in the scripts section of package.json. This option can be used when it's desirable to optionally run a script when it's present and fail if the script fails. This is useful, for example, when running scripts that may only apply for some builds in an otherwise generic CI setup.

If true, npm does not run scripts specified in package.json files.

A module that will be loaded by the npm init command. See the documentation for the init-package-json module for more information, or npm-init.

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

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

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

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

The value that npm init should use by default for the package version number, if not already set in package.json.

Whether or not to output JSON data, rather than the normal output.

This feature is currently experimental, and the output data structures for many commands is either not implemented in JSON yet, or subject to change. Only the output from npm ls --json and npm search --json are currently valid.

A client key to pass when accessing the registry. Values should be in PEM format with newlines replaced by the string "\n". For example:

key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"

It is not the path to a key file (and there is no "keyfile" option).

Causes npm to install the package such that versions of npm prior to 1.4, such as the one included with node 0.8, can install the package. This eliminates all automatic deduping. If used with global-style this option will be preferred.

If true, then local installs will link if there is a suitable globally installed package.

Note that this means that local installs can cause things to be installed into the global space at the same time. The link is only done if one of the two conditions are met:

The IP address of the local interface to use when making connections to the npm registry. Must be IPv4 in versions of Node prior to 0.12.

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

Any logs of a higher level than the setting are shown. The default is "warn", which shows warn and error output.

This is the stream that is passed to the npmlog module at run time.

It cannot be set from the command line, but if you are using npm programmatically, you may wish to send logs to somewhere other than stderr.

If the color config is set to true, then this stream will receive colored output if it is a TTY.

The maximum number of log files to store.

Show extended information in npm ls and npm search.

The maximum number of connections to use per origin (protocol/host/port combination). Passed to the http Agent used to make the request.

Commit message which is used by npm version when creating version commit.

Any "%s" in the message will be replaced with the version number.

The registry you want to send cli metrics to if send-metrics is true.

The node version to use when checking a package's engines map.

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

When "dev" or "development" and running local npm install without any arguments, only devDependencies (and their dependencies) are installed.

When "dev" or "development" and running local npm ls, npm outdated, or npm update, is an alias for --dev.

When "prod" or "production" and running local npm install without any arguments, only non-devDependencies (and their dependencies) are installed.

When "prod" or "production" and running local npm ls, npm outdated, or npm update, is an alias for --production.

Attempt to install packages in the optionalDependencies object. Note that if these packages fail to install, the overall installation process is not aborted.

Output parseable results from commands that write to standard output. For npm search, this will be tab-separated table format.

The location to install global items. If set on the command line, then it forces non-global commands to run in the specified folder.

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.

When set to true, npm will display a progress bar during time intensive operations, if process.stderr is a TTY.

Set to false to suppress the progress bar.

Whether or not to include proprietary extended attributes in the tarballs created by npm.

Unless you are expecting to unpack package tarballs with something other than npm -- particularly a very outdated tar implementation -- leave this as true.

A proxy to use for outgoing http requests. If the HTTP_PROXY or http_proxy environment variables are set, proxy settings will be honored by the underlying request library.

Rebuild bundled dependencies after installation.

The base URL of the npm package registry.

Remove failed installs.

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

When used with the npm rm command, it removes it from the dependencies object.

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

If a package would be saved at install time by the use of --save, --save-dev, or --save-optional, then also put it in the bundleDependencies list.

When used with the npm rm command, it removes it from the bundledDependencies list.

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

When used with the npm rm command, it removes it from the devDependencies object.

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

Dependencies saved to package.json using --save, --save-dev or --save-optional will be configured with an exact version rather than using npm's default semver range operator.

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

When used with the npm rm command, it removes it from the devDependencies object.

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

Configure how versions of packages installed to a package.json file via --save or --save-dev get prefixed.

For example if a package has version 1.2.3, by default its version is set to ^1.2.3 which allows minor upgrades for that package, but after npm config set save-prefix='~' it would be set to ~1.2.3 which only allows patch upgrades.

Associate an operation with a scope for a scoped registry. Useful when logging in to a private registry for the first time: npm login --scope=@organization --registry=registry.organization.com, which will cause @organization to be mapped to the registry for future installation of packages specified according to the pattern @organization/package.

If set to true, add the directory in which the current node executable resides to the PATH environment variable when running scripts, even if that means that npm will invoke a different node executable than the one which it is running.

If set to false, never modify PATH with that.

If set to "warn-only", never modify PATH but print a warning if npm thinks that you may want to run it with true, e.g. because the node executable in the PATH is not the one npm was invoked with.

If set to auto, only add that directory to the PATH environment variable if the node executable with which npm was invoked and the one that is found first on the PATH are different.

Space-separated options that limit the results from search.

Space-separated options that are always passed to search.

Number of items to limit search results to. Will not apply at all to legacy searches.

The age of the cache, in seconds, before another registry request is made if using legacy search endpoint.

If true, success/failure metrics will be reported to the registry stored in metrics-registry. These requests contain the number of successful and failing runs of the npm CLI and the time period overwhich those counts were gathered. No identifying information is included in these requests.

The shell to run for the npm explore command.

If set to false, then ignore npm-shrinkwrap.json files when installing.

If set to true, then the npm version command will tag the version using -s to add a signature.

Note that git requires you to have set up GPG keys in your git configs for this to work properly.

Whether or not to do SSL key validation when making requests to the registry via https.

See also the ca config.

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.

If set, alters the prefix used when tagging a new version when performing a version increment using npm-version. To remove the prefix altogether, set it to the empty string: "".

Because other tools may rely on the convention that npm version tags look like v1.0.0, only use this property if it is absolutely necessary. In particular, use care when overriding this setting for public packages.

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

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

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.

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

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

The location of user-level configuration settings.

The "umask" value to use when setting the file creation mode on files and folders.

Folders and executables are given a mode which is 0777 masked against this value. Other files are given a mode which is 0666 masked against this value. Thus, the defaults are 0755 and 0644 respectively.

Sets a User-Agent to the request header

If true, output the npm version and exit successfully.

Only relevant when specified explicitly on the command line.

If true, output the npm version as well as node's process.versions map, and exit successfully.

Only relevant when specified explicitly on the command line.

The program to use to view help content.

Set to "browser" to view html help content in the default web browser.

Last modified January 26, 2017           Found a typo? Send a pull request!

npm-developers

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.

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.

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.

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 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 for more info.

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. Like git, npm looks for .npmignore and .gitignore files in all subdirectories of your package, not only the root directory.

.npmignore files follow the same pattern rules as .gitignore files:

By default, the following paths and files are ignored, so there's no need to add them to .npmignore explicitly:

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:

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.

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 with the adduser command. It works like this:

npm adduser

and then follow the prompts.

This is documented better in npm-adduser.

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.

Send emails, write blogs, blab in IRC.

Tell the world how easy it is to install your program!

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-disputes

This document describes the steps that you should take to resolve module name disputes with other npm publishers. It also describes special steps you should take about names you think infringe your trademarks.

This document is a clarification of the acceptable behavior outlined in the npm Code of Conduct, and nothing in this document should be interpreted to contradict any aspect of the npm Code of Conduct.

  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.

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. Alice writes a JavaScript module foo, which is not node-specific. Alice doesn't use node at all. Yusuf wants to use foo in node, so he wraps it in an npm module. Some time later, Alice starts using node, and wants to take over management of her program.

  2. Yusuf writes an npm module foo, and publishes it. Perhaps much later, Alice finds a bug in foo, and fixes it. She sends a pull request to Yusuf, but Yusuf 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. Alice would like to publish a new foo, but can't, because the name is taken.

  3. Yusuf 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. Alice 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 installfoo`` is some different thing.

  4. Yusuf 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, Alice writes a much more complete foo parser, but can't publish, because Yusuf's foo is in the way.

  5. npm owner ls foo. This will tell Alice the email address of the owner (Yusuf).

  6. Alice emails Yusuf, explaining the situation as respectfully as possible, and what she would like to do with the module name. She adds the npm support staff support@npmjs.com to the CC list of the email. Mention in the email that Yusuf can run npm owner add alice foo to add Alice as an owner of the foo package.

  7. After a reasonable amount of time, if Yusuf has not responded, or if Yusuf and Alice 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.)

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.

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.
  7. Other things forbidden by the npm Code of Conduct such as hateful language, pornographic content, or harassment.

If you see bad behavior like this, please report it to abuse@npmjs.com right away. You are never expected to resolve abusive behavior on your own. We are here to help.

If you think another npm publisher is infringing your trademark, such as by using a confusingly similar package name, email abuse@npmjs.com with a link to the package or user account on https://npmjs.com. Attach a copy of your trademark registration certificate.

If we see that the package's publisher is intentionally misleading others by misusing your registered mark without permission, we will transfer the package name to you. Otherwise, we will contact the package publisher and ask them to clear up any confusion with changes to their package's README file or metadata.

This is a living document and may be updated from time to time. Please refer to the git history for this document to view the changes.

Copyright (C) npm, Inc., All rights reserved

This document may be reused under a Creative Commons Attribution-ShareAlike License.

Last modified January 13, 2017           Found a typo? Send a pull request!

npm-orgs

There are three levels of org users:

  1. Super admin, controls billing & adding people to the org.
  2. Team admin, manages team membership & package access.
  3. Developer, works on packages they are given access to.

The super admin is the only person who can add users to the org because it impacts the monthly bill. The super admin will use the website to manage membership. Every org has a developers team that all users are automatically added to.

The team admin is the person who manages team creation, team membership, and package access for teams. The team admin grants package access to teams, not individuals.

The developer will be able to access packages based on the teams they are on. Access is either read-write or read-only.

There are two main commands:

  1. npm team see npm-team for more details
  2. npm access see npm-access for more details
npm team ls <org>:developers
npm team create <org:team>
npm team add <org:team> <user>
npm init --scope=<org>

to scope it for your org & publish as usual

npm access grant <read-only|read-write> <org:team> [<package>]
npm access revoke <org:team> [<package>]
npm access ls-packages <org> <user>
npm access ls-packages <org:team>
npm access ls-collaborators <pkg>

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-registry

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 https://registry.npmjs.org/. It is powered by a CouchDB database, of which there is a public mirror at https://skimdb.npmjs.com/registry. The code for the couchapp is available at https://github.com/npm/npm-registry-couchapp.

The registry URL used is determined by the scope of the package (see npm-scope). If no scope is specified, the default registry is used, which is supplied by the registry config parameter. See npm-config, npmrc, and npm-config for more on managing npm's configuration.

Yes.

When making requests of the registry npm adds two headers with information about your environment:

The npm registry does not to correlate the information in these headers with any authenticated accounts that may be used in the same requests.

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 option for that publish command.

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 for more info on what goes in the package.json file.

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.

No, but it's way easier. Basically, yes, you do, or you have to effectively implement the entire CouchDB API anyway.

Yes, head over to https://npmjs.com/

Last modified December 16, 2016           Found a typo? Send a pull request!

npm-removal

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

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.

Note that this is only necessary for globally-installed packages. Local installs are completely contained within a project's node_modules folder. Delete that folder, and everything is gone (unless a package's install script is particularly ill-behaved).

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.

To remove everything npm-related manually:

rm -rf /usr/local/{lib/node{,/.npm,_modules},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{,/.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.)

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-scope

All npm packages have a name. Some package names also have a scope. A scope follows the usual rules for package names (URL-safe characters, no leading dots or underscores). When used in package names, scopes are preceded by an @ symbol and followed by a slash, e.g.

@somescope/somepackagename

Scopes are a way of grouping related packages together, and also affect a few things about the way npm treats the package.

Each npm user/organization has their own scope, and only you can add packages in your scope. This means you don't have to worry about someone taking your package name ahead of you. Thus it is also a good way to signal official packages for organizations.

Scoped packages can be published and installed as of npm@2 and are supported by the primary npm registry. Unscoped packages can depend on scoped packages and vice versa. The npm client is backwards-compatible with unscoped registries, so it can be used to work with scoped and unscoped registries at the same time.

Scoped packages are installed to a sub-folder of the regular installation folder, e.g. if your other packages are installed in node_modules/packagename, scoped modules will be installed in node_modules/@myorg/packagename. The scope folder (@myorg) is simply the name of the scope preceded by an @ symbol, and can contain any number of scoped packages.

A scoped package is installed by referencing it by name, preceded by an @ symbol, in npm install:

npm install @myorg/mypackage

Or in package.json:

"dependencies": {
  "@myorg/mypackage": "^1.3.0"
}

Note that if the @ symbol is omitted, in either case, npm will instead attempt to install from GitHub; see npm-install.

Because scoped packages are installed into a scope folder, you have to include the name of the scope when requiring them in your code, e.g.

require('@myorg/mypackage')

There is nothing special about the way Node treats scope folders. This simply requires the mypackage module in the folder named @myorg.

Scoped packages can be published from the CLI as of npm@2 and can be published to any registry that supports them, including the primary npm registry.

(As of 2015-04-19, and with npm 2.0 or better, the primary npm registry does support scoped packages.)

If you wish, you may associate a scope with a registry; see below.

To publish a public scoped package, you must specify --access public with the initial publication. This will publish the package and set access to public as if you had run npm access public after publishing.

To publish a private scoped package to the npm registry, you must have an npm Private Modules account.

You can then publish the module with npm publish or npm publish --access restricted, and it will be present in the npm registry, with restricted access. You can then change the access permissions, if desired, with npm access or on the npmjs.com website.

Scopes can be associated with a separate registry. This allows you to seamlessly use a mix of packages from the primary npm registry and one or more private registries, such as npm Enterprise.

You can associate a scope with a registry at login, e.g.

npm login --registry=http://reg.example.com --scope=@myco

Scopes have a many-to-one relationship with registries: one registry can host multiple scopes, but a scope only ever points to one registry.

You can also associate a scope with a registry using npm config:

npm config set @myco:registry http://reg.example.com

Once a scope is associated with a registry, any npm install for a package with that scope will request packages from that registry instead. Any npm publish for a package name that contains the scope will be published to that registry instead.

Last modified January 26, 2017           Found a typo? Send a pull request!

npm-scripts

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

Additionally, arbitrary scripts can be executed by running npm run-script <stage>. Pre and post commands with matching names will be run for those as well (e.g. premyscript, myscript, postmyscript). Scripts from dependencies can be run with npm explore <pkg> -- npm run <stage>.

Since npm@1.1.71, the npm CLI has run the prepublish script for both npm publish and npm install, because it's a convenient way to prepare a package for use (some common use cases are described in the section below). It has also turned out to be, in practice, very confusing. As of npm@4.0.0, a new event has been introduced, prepare, that preserves this existing behavior. A new event, prepublishOnly has been added as a transitional strategy to allow users to avoid the confusing behavior of existing npm versions and only run on npm publish (for instance, running the tests one last time to ensure they're in good shape).

IMPORTANT: As of npm@5, prepublish will only be run for npm publish. This will make its behavior identical to prepublishOnly, so npm@6 or later may drop support for the use of prepublishOnly, and then maybe we can all forget this embarrassing thing ever happened.

See https://github.com/npm/npm/issues/10074 for a much lengthier justification, with further reading, for this change.

If you need to perform operations on your package before it is used, in a way that is not dependent on the operating system or architecture of the target system, use a prepublish script. This includes tasks such as:

The advantage of doing these things at prepublish time is that they can be done once, in a single place, thus reducing complexity and variability. Additionally, this means that:

npm will default some script values based on package contents.

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.

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.

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.

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

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

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"

For example, if your package.json contains this:

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

then scripts/install.js will be called for the install and post-install stages of the lifecycle, and scripts/uninstall.js will be called when the package is uninstalled. Since scripts/install.js is running for two 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"
  }
}

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.

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.

Last modified December 16, 2016           Found a typo? Send a pull request!

semver

$ npm install semver
$ node
var semver = require('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

SemVer 5.1.0

A JavaScript implementation of the http://semver.org/ specification
Copyright Isaac Z. Schlueter

Usage: semver [options] <version> [<version> [...]]
Prints valid versions sorted by SemVer precedence

Options:
-r --range <range>
        Print versions that match the specified range.

-i --increment [<level>]
        Increment a version by the specified level.  Level can
        be one of: major, minor, patch, premajor, preminor,
        prepatch, or prerelease.  Default level is 'patch'.
        Only one version may be specified.

--preid <identifier>
        Identifier to be used to prefix premajor, preminor,
        prepatch or prerelease version increments.

-l --loose
        Interpret versions and ranges loosely

Program exits successfully if any valid version satisfies
all supplied ranges, and prints all satisfying versions.

If no satisfying versions are found, then exits failure.

Versions are printed in ascending order, so supplying
multiple versions to the utility will just sort them.

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.

A version range is a set of comparators which specify versions that satisfy the range.

A comparator is composed of an operator and a version. The set of primitive operators is:

For example, the comparator >=1.2.7 would match the versions 1.2.7, 1.2.8, 2.5.3, and 1.3.9, but not the versions 1.2.6 or 1.1.0.

Comparators can be joined by whitespace to form a comparator set, which is satisfied by the intersection of all of the comparators it includes.

A range is composed of one or more comparator sets, joined by ||. A version matches a range if and only if every comparator in at least one of the ||-separated comparator sets is satisfied by the version.

For example, the range >=1.2.7 <1.3.0 would match the versions 1.2.7, 1.2.8, and 1.2.99, but not the versions 1.2.6, 1.3.0, or 1.1.0.

The range 1.2.7 || >=1.2.9 <2.0.0 would match the versions 1.2.7, 1.2.9, and 1.4.6, but not the versions 1.2.8 or 2.0.0.

If a version has a prerelease tag (for example, 1.2.3-alpha.3) then it will only be allowed to satisfy comparator sets if at least one comparator with the same [major, minor, patch] tuple also has a prerelease tag.

For example, the range >1.2.3-alpha.3 would be allowed to match the version 1.2.3-alpha.7, but it would not be satisfied by 3.4.5-alpha.9, even though 3.4.5-alpha.9 is technically "greater than" 1.2.3-alpha.3 according to the SemVer sort rules. The version range only accepts prerelease tags on the 1.2.3 version. The version 3.4.5 would satisfy the range, because it does not have a prerelease flag, and 3.4.5 is greater than 1.2.3-alpha.7.

The purpose for this behavior is twofold. First, prerelease versions frequently are updated very quickly, and contain many breaking changes that are (by the author's design) not yet fit for public consumption. Therefore, by default, they are excluded from range matching semantics.

Second, a user who has opted into using a prerelease version has clearly indicated the intent to use that specific set of alpha/beta/rc versions. By including a prerelease tag in the range, the user is indicating that they are aware of the risk. However, it is still not appropriate to assume that they have opted into taking a similar risk on the next set of prerelease versions.

The method .inc takes an additional identifier string argument that will append the value of the string as a prerelease identifier:

> semver.inc('1.2.3', 'prerelease', 'beta')
'1.2.4-beta.0'

command-line example:

$ semver 1.2.3 -i prerelease --preid beta
1.2.4-beta.0

Which then can be used to increment further:

$ semver 1.2.4-beta.0 -i prerelease
1.2.4-beta.1

Advanced range syntax desugars to primitive comparators in deterministic ways.

Advanced ranges may be combined in the same way as primitive comparators using white space or ||.

Specifies an inclusive set.

If a partial version is provided as the first version in the inclusive range, then the missing pieces are replaced with zeroes.

If a partial version is provided as the second version in the inclusive range, then all versions that start with the supplied parts of the tuple are accepted, but nothing that would be greater than the provided tuple parts.

Any of X, x, or * may be used to "stand in" for one of the numeric values in the [major, minor, patch] tuple.

A partial version range is treated as an X-Range, so the special character is in fact optional.

Allows patch-level changes if a minor version is specified on the comparator. Allows minor-level changes if not.

Allows changes that do not modify the left-most non-zero digit in the [major, minor, patch] tuple. In other words, this allows patch and minor updates for versions 1.0.0 and above, patch updates for versions 0.X >=0.1.0, and no updates for versions 0.0.X.

Many authors treat a 0.x version as if the x were the major "breaking-change" indicator.

Caret ranges are ideal when an author may make breaking changes between 0.2.4 and 0.3.0 releases, which is a common practice. However, it presumes that there will not be breaking changes between 0.2.4 and 0.2.5. It allows for changes that are presumed to be additive (but non-breaking), according to commonly observed practices.

When parsing caret ranges, a missing patch value desugars to the number 0, but will allow flexibility within that value, even if the major and minor versions are both 0.

A missing minor and patch values will desugar to zero, but also allow flexibility within those values, even if the major version is zero.

Putting all this together, here is a Backus-Naur grammar for ranges, for the benefit of parser authors:

range-set  ::= range ( logical-or range ) *
logical-or ::= ( ' ' ) * '||' ( ' ' ) *
range      ::= hyphen | simple ( ' ' simple ) * | ''
hyphen     ::= partial ' - ' partial
simple     ::= primitive | partial | tilde | caret
primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' | ) partial
partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
xr         ::= 'x' | 'X' | '*' | nr
nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
tilde      ::= '~' partial
caret      ::= '^' partial
qualifier  ::= ( '-' pre )? ( '+' build )?
pre        ::= parts
build      ::= parts
parts      ::= part ( '.' part ) *
part       ::= nr | [-0-9A-Za-z]+

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.

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.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-access

npm access public [<package>]
npm access restricted [<package>]

npm access grant <read-only|read-write> <scope:team> [<package>]
npm access revoke <scope:team> [<package>]

npm access ls-packages [<user>|<scope>|<scope:team>]
npm access ls-collaborators [<package> [<user>]]
npm access edit [<package>]

Used to set access controls on private packages.

For all of the subcommands, npm access will perform actions on the packages in the current working directory if no package name is passed to the subcommand.

npm access always operates directly on the current registry, configurable from the command line using --registry=<registry url>.

Unscoped packages are always public.

Scoped packages default to restricted, but you can either publish them as public using npm publish --access=public, or set their access as public using npm access public after the initial publish.

You must have privileges to set the access of a package:

If your account is not paid, then attempts to publish scoped packages will fail with an HTTP 402 status code (logically enough), unless you use --access=public.

Management of teams and team memberships is done with the npm team command.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-adduser

npm adduser [--registry=url] [--scope=@orgname] [--always-auth]

aliases: login, add-user

Create or verify a user named <username> in the specified registry, and save the credentials to the .npmrc file. If no registry is specified, the default registry will be used (see npm-config).

The username, password, and email are read in from prompts.

To reset your password, go to https://www.npmjs.com/forgot

To change your email address, go to https://www.npmjs.com/email-edit

You may use this command multiple times with the same user account to authorize on a new machine. When authenticating on a new machine, the username, password and email address must all match with your existing record.

npm login is an alias to adduser and behaves exactly the same way.

Default: https://registry.npmjs.org/

The base URL of the npm package registry. If scope is also specified, this registry will only be used for packages with that scope. scope defaults to the scope of the project directory you're currently in, if any. See npm-scope.

Default: none

If specified, the user and login credentials given will be associated with the specified scope. See npm-scope. You can use both at the same time, e.g.

npm adduser --registry=http://myregistry.example.com --scope=@myco

This will set a registry for the given scope and login or create a user for that registry at the same time.

Default: false

If specified, save configuration indicating that all requests to the given registry should include authorization information. Useful for private registries. Can be used with --registry and / or --scope, e.g.

npm adduser --registry=http://private-registry.example.com --always-auth

This will ensure that all requests to that registry (including for tarballs) include an authorization header. This setting may be necessary for use with private registries where metadata and package tarballs are stored on hosts with different hostnames. See always-auth in npm-config for more details on always-auth. Registry-specific configuration of always-auth takes precedence over any global configuration.

Last modified January 13, 2017           Found a typo? Send a pull request!

npm-bin

npm bin [-g|--global]

Print the folder where npm will install executables.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-bugs

npm bugs [<pkgname>]

aliases: issues

This command tries to guess at the likely location of a package's bug tracker URL, and then tries to open it using the --browser config param. If no package name is provided, it will search for a package.json in the current folder and use the name property.

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

The base URL of the npm package registry.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-build

npm build [<package-folder>]

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

It should generally be called during installation, but if you need to run it directly, run:

npm run-script build

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-bundle

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.

Last modified October 13, 2016           Found a typo? Send a pull request!

npm-cache

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>]
aliases: npm cache clear, npm cache rm

Used to add, list, or clean the npm cache folder.

npm stores cache data in the directory specified in npm config get cache. 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. This is stored in {cache}/{hostname}/{path}/.cache.json.

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.

Default: ~/.npm on Posix, or %AppData%/npm-cache on Windows.

The root cache folder.

Last modified January 16, 2017           Found a typo? Send a pull request!

npm-completion

source <(npm completion)

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:

npm completion >> ~/.bashrc
npm completion >> ~/.zshrc

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.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-config

npm config set <key> <value> [-g|--global]
npm config get <key>
npm config delete <key>
npm config list
npm config edit
npm get <key>
npm set <key> <value> [-g|--global]

aliases: c

npm gets its config settings from the command line, environment variables, npmrc files, and in some cases, the package.json file.

See npmrc for more information about the npmrc files.

See npm-config for a more thorough discussion of the mechanisms involved.

The npm config command can be used to update and edit the contents of the user and global npmrc files.

Config supports the following sub-commands:

npm config set key value

Sets the config key to the value.

If value is omitted, then it sets it to "true".

npm config get key

Echo the config value to stdout.

npm config list

Show all the config settings.

npm config delete key

Deletes the key from all configuration files.

npm config edit

Opens the config file in an editor. Use the --global flag to edit the global config.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-dedupe

npm dedupe
npm ddp

aliases: find-dupes, ddp

Searches the local package tree and attempts to simplify the overall structure by moving dependencies further up the tree, where they can be more effectively shared by multiple dependent packages.

For example, consider this dependency graph:

a
+-- b <-- depends on c@1.0.x
|   `-- c@1.0.3
`-- d <-- depends on c@~1.0.9
    `-- c@1.0.10

In this case, npm-dedupe will transform the tree to:

a
+-- b
+-- d
`-- c@1.0.10

Because of the hierarchical nature of node's module lookup, b and d will both get their dependency met by the single c package at the root level of the tree.

The deduplication algorithm walks the tree, moving each dependency as far up in the tree as possible, even if duplicates are not found. This will result in both a flat and deduplicated tree.

If a suitable version exists at the target location in the tree already, then it will be left untouched, but the other duplicates will be deleted.

Arguments are ignored. Dedupe always acts on the entire tree.

Modules

Note that this operation transforms the dependency tree, but will never result in new modules being installed.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-deprecate

npm deprecate <pkg>[@<version>] <message>

This command will update the npm registry entry for a package, providing a deprecation warning to all who attempt to install it.

It works on version ranges as well as specific versions, so you can do something like this:

npm deprecate my-thing@"< 0.2.3" "critical bug fixed in v0.2.3"

Note that you must be the package owner to deprecate something. See the owner and adduser help topics.

To un-deprecate a package, specify an empty string ("") for the message argument.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-dist-tag

npm dist-tag add <pkg>@<version> [<tag>]
npm dist-tag rm <pkg> <tag>
npm dist-tag ls [<pkg>]

aliases: dist-tags

Add, remove, and enumerate distribution tags on a package:

A tag can be used when installing packages as a reference to a version instead of using a specific version number:

npm install <name>@<tag>

When installing dependencies, a preferred tagged version may be specified:

npm install --tag <tag>

This also applies to npm dedupe.

Publishing a package sets the latest tag to the published version unless the --tag option is used. For example, npm publish --tag=beta.

By default, npm install <pkg> (without any @<version> or @<tag> specifier) installs the latest tag.

Tags can be used to provide an alias instead of version numbers.

For example, a project might choose to have multiple streams of development and use a different tag for each stream, e.g., stable, beta, dev, canary.

By default, the latest tag is used by npm to identify the current version of a package, and npm install <pkg> (without any @<version> or @<tag> specifier) installs the latest tag. Typically, projects only use the latest tag for stable release versions, and use other tags for unstable versions such as prereleases.

The next tag is used by some projects to identify the upcoming version.

By default, other than latest, no tag has any special significance to npm itself.

This command used to be known as npm tag, which only created new tags, and so had a different syntax.

Tags must share a namespace with version numbers, because they are specified in the same slot: npm install <pkg>@<version> vs npm install <pkg>@<tag>.

Tags that can be interpreted as valid semver ranges will be rejected. For example, v1.4 cannot be used as a tag, because it is interpreted by semver as >=1.4.0 <1.5.0. See https://github.com/npm/npm/issues/6082.

The simplest way to avoid semver problems with tags is to use tags that do not begin with a number or the letter v.

Last modified December 16, 2016           Found a typo? Send a pull request!

npm-docs

npm docs [<pkgname> [<pkgname> ...]]
npm docs .
npm home [<pkgname> [<pkgname> ...]]
npm home .

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. You can pass multiple package names at once. If no package name is provided, it will search for a package.json in the current folder and use the name property.

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

The base URL of the npm package registry.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-doctor

npm doctor

npm doctor runs a set of checks to ensure that your npm installation has what it needs to manage your JavaScript packages. npm is mostly a standalone tool, but it does have some basic requirements that must be met:

Without all of these working properly, npm may not work properly. Many issues are often attributable to things that are outside npm's code base, so npm doctor confirms that the npm installation is in a good state.

Also, in addition to this, there are also very many issue reports due to using old versions of npm. Since npm is constantly improving, running npm@latest is better than an old version.

npm doctor verifies the following items in your environment, and if there are any recommended changes, it will display them.

By default, npm installs from the primary npm registry, registry.npmjs.org. npm doctor hits a special ping endpoint within the registry. This can also be checked with npm ping. If this check fails, you may be using a proxy that needs to be configured, or may need to talk to your IT staff to get access over HTTPS to registry.npmjs.org.

This check is done against whichever registry you've configured (you can see what that is by running npm config get registry), and if you're using a private registry that doesn't support the /whoami endpoint supported by the primary registry, this check may fail.

While Node.js may come bundled with a particular version of npm, it's the policy of the CLI team that we recommend all users run npm@latest if they can. As the CLI is maintained by a small team of contributors, there are only resources for a single line of development, so npm's own long-term support releases typically only receive critical security and regression fixes. The team believes that the latest tested version of npm is almost always likely to be the most functional and defect-free version of npm.

For most users, in most circumstances, the best version of Node will be the latest long-term support (LTS) release. Those of you who want access to new ECMAscript features or bleeding-edge changes to Node's standard library may be running a newer version, and some of you may be required to run an older version of Node because of enterprise change control policies. That's OK! But in general, the npm team recommends that most users run Node.js LTS.

Some of you may be installing from private package registries for your project or company. That's great! Others of you may be following tutorials or StackOverflow questions in an effort to troubleshoot problems you may be having. Sometimes, this may entail changing the registry you're pointing at. This part of npm doctor just lets you, and maybe whoever's helping you with support, know that you're not using the default registry.

While it's documented in the README, it may not be obvious that npm needs Git installed to do many of the things that it does. Also, in some cases – especially on Windows – you may have Git set up in such a way that it's not accessible via your PATH so that npm can find it. This check ensures that Git is available.

When an npm package is published, the publishing process generates a checksum that npm uses at install time to verify that the package didn't get corrupted in transit. npm doctor uses these checksums to validate the package tarballs in your local cache (you can see where that cache is located with npm config get cache, and see what's in that cache with npm cache ls – probably more than you were expecting!). In the event that there are corrupt packages in your cache, you should probably run npm cache clean and reset the cache.

Last modified January 16, 2017           Found a typo? Send a pull request!

npm-edit

npm edit <pkg>[@<version>]

Opens the package folder in the default editor (or whatever you've configured as the npm editor config -- see npm-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.

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

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-explore

npm explore <pkg> [ -- <cmd>]

Spawn a subshell in the directory of the installed package specified.

If a command is specified, then it is run in the subshell, which then immediately terminates.

This is particularly handy in the case of git submodules in the node_modules folder:

npm explore some-dependency -- git pull origin master

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

The shell to run for the npm explore command.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-help

npm help <term> [<terms..>]

If supplied a topic, then show the appropriate documentation page.

If the topic does not exist, or if multiple terms are provided, then run the help-search command to find a match. Note that, if help-search finds a single subject, then it will run help on that topic, so unique matches are equivalent to specifying a topic name.

The program to use to view help content.

Set to "browser" to view html help content in the default web browser.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-help-search

npm help-search <text>

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.

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.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-init

npm init [-f|--force|-y|--yes]

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.

If you invoke it with -f, --force, -y, or --yes, it will use only defaults and not prompt you for any options.

The scope under which the new module should be created.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-install

npm install (with no args, in package dir)
npm install [<@scope>/]<name>
npm install [<@scope>/]<name>@<tag>
npm install [<@scope>/]<name>@<version>
npm install [<@scope>/]<name>@<version range>
npm install <tarball file>
npm install <tarball url>
npm install <folder>

alias: npm i
common options: [-S|--save|-D|--save-dev|-O|--save-optional] [-E|--save-exact] [-B|--save-bundle] [--dry-run]

This command installs a package, and any packages that it depends on. If the package has a shrinkwrap file, the installation of dependencies will be driven by that. See npm-shrinkwrap.

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

**Note**: If there is a file or folder named `<name>` in the current
working directory, then it will try to install that, and only try to
fetch the package by name if it is not valid.

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. If a tag with the given name exists, the tagged version is preferred over newer versions.

The --dry-run argument will report in the usual way what the install would have done without actually installing anything.

The -f or --force argument will force npm to fetch remote resources even if a local copy exists on disk.

npm install sax --force

The -g or --global argument will cause npm to install the package globally rather than locally. See npm-folders.

The --global-style argument will cause npm to install the package into your local node_modules folder with the same layout it uses with the global node_modules folder. Only your direct dependencies will show in node_modules and everything they depend on will be flattened in their node_modules folders. This obviously will eliminate some deduping.

The --ignore-scripts argument will cause npm to not execute any scripts defined in the package.json. See npm-scripts.

The --legacy-bundling argument will cause npm to install the package such that versions of npm prior to 1.4, such as the one included with node 0.8, can install the package. This eliminates all automatic deduping.

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

The --no-bin-links argument will prevent npm from creating symlinks for any binaries the package might contain.

The --no-optional argument will prevent optional dependencies from being installed.

The --no-shrinkwrap argument, which will ignore an available shrinkwrap file and use the package.json instead.

The --nodedir=/path/to/node/source argument will allow npm to find the node source code so that npm can compile native modules.

The --only={prod[uction]|dev[elopment]} argument will cause either only devDependencies or only non-devDependencies to be installed regardless of the NODE_ENV.

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

To install a package, npm uses the following algorithm:

load the existing node_modules tree from disk
clone the tree
fetch the package.json and assorted metadata and add it to the clone
walk the clone and add any missing dependencies
  dependencies will be added as close to the top as is possible
  without breaking any other modules
compare the original tree with the cloned tree and make a list of
actions to take to convert one to the other
execute all of the actions, deepest first
  kinds of actions are install, update, remove and move

For this package{dep} structure: A{B,C}, B{C}, C{D}, this algorithm produces:

A
+-- B
+-- C
+-- D

That is, the dependency from B to C is satisfied by the fact that A already caused C to be installed at a higher level. D is still installed at the top level because nothing conflicts with it.

For A{B,C}, B{C,D@1}, C{D@2}, this algorithm produces:

A
+-- B
+-- C
   `-- D@2
+-- D@1

Because B's D@1 will be installed in the top level, C now has to install D@2 privately for itself.

See npm-folders for a more detailed description of the specific folder structures that npm creates.

npm will refuse to install any package with an identical name to the current package. This can be overridden with the --force flag, but in most cases can simply be addressed by changing the local package name.

There are some very rare and pathological edge-cases where a cycle can cause npm to try to install a never-ending tree of packages. Here is the simplest case:

A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ...

where A is some version of a package, and A' is a different version of the same package. Because B depends on a different version of A than the one that is already in the tree, it must install a separate copy. The same is true of A', which must install B'. Because B' depends on the original version of A, which has been overridden, the cycle falls into infinite regress.

To avoid this situation, npm flat-out refuses to install any name@version that is already present anywhere in the tree of package folder ancestors. A more correct, but more complex, solution would be to symlink the existing version into the new location. If this ever affects a real use-case, it will be investigated.

Last modified January 13, 2017           Found a typo? Send a pull request!

npm install-test -- Install package(s) and run tests

npm install-test (with no args, in package dir)
npm install-test [<@scope>/]<name>
npm install-test [<@scope>/]<name>@<tag>
npm install-test [<@scope>/]<name>@<version>
npm install-test [<@scope>/]<name>@<version range>
npm install-test <tarball file>
npm install-test <tarball url>
npm install-test <folder>

alias: npm it
common options: [--save|--save-dev|--save-optional] [--save-exact] [--dry-run]

This command runs an npm install followed immediately by an npm test. It takes exactly the same arguments as npm install.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-link

npm link (in package dir)
npm link [<@scope>/]<pkg>[@<version>]

alias: npm ln

Package linking is a two-step process.

First, npm link in a package folder will create a symlink in the global folder {prefix}/lib/node_modules/<package> that links to the package where the npm link command was executed. (see npm-config for the value of prefix). It will also link any bins in the package to {prefix}/bin/{name}.

Next, in some other location, npm link package-name will create a symbolic link from globally-installed package-name to node_modules/ of the current folder.

Note that package-name is taken from package.json, not from directory name.

The package name can be optionally prefixed with a scope. See npm-scope. The scope must be preceded by an @-symbol and followed by a slash.

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/node-redis/. Note that the link should be to the package name, not the directory name for that package.

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 node-redis

That is, it first creates a global link, and then links the global installation target into your project's node_modules folder.

If your linked package is scoped (see npm-scope) your link command must include that scope, e.g.

npm link @myorg/privatepackage

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-logout

npm logout [--registry=<url>] [--scope=<@scope>]

When logged into a registry that supports token-based authentication, tell the server to end this token's session. This will invalidate the token everywhere you're using it, not just for the current environment.

When logged into a legacy registry that uses username and password authentication, this will clear the credentials in your user configuration. In this case, it will only affect the current environment.

If --scope is provided, this will find the credentials for the registry connected to that scope, if set.

Default: https://registry.npmjs.org/

The base URL of the npm package registry. If scope is also specified, it takes precedence.

Default: The scope of your current project, if any, otherwise none.

If specified, you will be logged out of the specified scope. See npm-scope.

npm logout --scope=@myco

Last modified December 16, 2016           Found a typo? Send a pull request!

npm-ls

npm ls [[<@scope>/]<pkg> ...]

aliases: list, la, ll

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

Positional arguments are name@version-range identifiers, which will limit the results to only the paths to the packages named. Note that nested packages will also show the paths to the specified packages. For example, running npm ls promzard in npm's source tree will show:

npm@@VERSION@ /path/to/npm
└─┬ init-package-json@0.0.4
  └── promzard@0.1.5

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

If a project specifies git urls for dependencies these are shown in parentheses after the name@version to make it easier for users to recognize potential forks of a project.

The tree shown is the logical dependency tree, based on package dependencies, not the physical layout of your node_modules folder.

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

Show information in JSON format.

Show extended information.

Show parseable output instead of tree view.

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

Max display depth of the dependency tree.

Display only the dependency tree for packages in dependencies.

Display only the dependency tree for packages in devDependencies.

When "dev" or "development", is an alias to dev.

When "prod" or "production", is an alias to production.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm

npm <command> [args]

@VERSION@

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.

You probably got npm because you want to install stuff.

Use npm install blerg to install the latest version of "blerg". Check out npm-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.

If a package references to another package with a git URL, npm depends on a preinstalled git.

If one of the packages npm tries to install is a native node module and requires compiling of C++ Code, npm will use node-gyp for that task. For a Unix system, node-gyp needs Python, make and a buildchain like GCC. On Windows, Python and Microsoft Visual Studio C++ are needed. Python 3 is not supported by node-gyp. For more information visit the node-gyp repository and the node-gyp Wiki.

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

In particular, npm has two modes of operation:

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

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

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

See npm-config for much much more information.

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, read the contributing guidelines and check the issues list.

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.

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

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-outdated

npm outdated [[<@scope>/]<pkg> ...]

This command will check the registry to see if any (or, specific) installed packages are currently outdated.

In the output:

$ npm outdated
Package      Current   Wanted   Latest  Location
glob          5.0.15   5.0.15    6.0.1  test-outdated-output
nothingness    0.0.3      git      git  test-outdated-output
npm            3.5.1    3.5.2    3.5.1  test-outdated-output
local-dev      0.0.3   linked   linked  test-outdated-output
once           1.3.2    1.3.3    1.3.3  test-outdated-output

With these dependencies:

{
  "glob": "^5.0.15",
  "nothingness": "github:othiym23/nothingness#master",
  "npm": "^3.5.1",
  "once": "^1.3.1"
}

A few things to note:

Show information in JSON format.

Show extended information.

Show parseable output instead of tree view.

Check packages in the global install prefix instead of in the current project.

Max depth for checking dependency tree.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-owner

npm owner add <user> [<@scope>/]<pkg>
npm owner rm <user> [<@scope>/]<pkg>
npm owner ls [<@scope>/]<pkg>

aliases: author

Manage ownership of published packages.

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.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-pack

npm pack [[<@scope>/]<pkg>...]

For anything that's installable (that is, a package folder, tarball, tarball url, name@tag, name@version, name, or scoped 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.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-ping

npm ping [--registry <registry>]

Ping the configured or given npm registry and verify authentication.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-prefix

npm prefix [-g]

Print the local prefix to standard out. This is the closest parent directory to contain a package.json file unless -g is also specified.

If -g is specified, this will be the value of the global prefix. See npm-config for more detail.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-prune

npm prune [[<@scope>/]<pkg>...] [--production]

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.

If the --production flag is specified or the NODE_ENV environment variable is set to production, this command will remove the packages specified in your devDependencies. Setting --production=false will negate NODE_ENV being set to production.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-publish

npm publish [<tarball>|<folder>] [--tag <tag>] [--access <public|restricted>]

Publishes '.' if no argument supplied
Sets tag 'latest' if no --tag specified

Publishes a package to the registry so that it can be installed by name. All files in the package directory are included if no local .gitignore or .npmignore file exists. If both files exist and a file is ignored by .gitignore but not by .npmignore then it will be included. See npm-developers for full details on what's included in the published package, as well as details on how the package is built.

By default npm will publish to the public registry. This can be overridden by specifying a different default registry or using a npm-scope in the name (see package.json).

Fails if the package name and version combination already exists in the specified registry.

Once a package is published with a given name and version, that specific name and version combination can never be used again, even if it is removed with npm-unpublish.

For a "dry run" that does everything except actually publishing to the registry, see npm-pack, which figures out the files to be included and packs them into a tarball to be uploaded to the registry.

Last modified December 16, 2016           Found a typo? Send a pull request!

npm-rebuild

npm rebuild [[<@scope>/<name>]...]

alias: npm rb

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.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-repo

npm repo [<pkg>]

This command tries to guess at the likely location of a package's repository URL, and then tries to open it using the --browser config param. If no package name is provided, it will search for a package.json in the current folder and use the name property.

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

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-restart

npm restart [-- <args>]

This restarts a package.

This runs a package's "stop", "restart", and "start" scripts, and associated pre- and post- scripts, in the order given below:

  1. prerestart
  2. prestop
  3. stop
  4. poststop
  5. restart
  6. prestart
  7. start
  8. poststart
  9. postrestart

Note that the "restart" script is run in addition to the "stop" and "start" scripts, not instead of them.

This is the behavior as of npm major version 2. A change in this behavior will be accompanied by an increase in major version number

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-root

npm root [-g]

Print the effective node_modules folder to standard out.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-run-script

npm run-script <command> [-- <args>...]

alias: npm run

This runs an arbitrary command from a package's "scripts" object. If no "command" is provided, it will list the available scripts. run[-script] is used by the test, start, restart, and stop commands, but can be called directly, as well. When the scripts in the package are printed out, they're separated into lifecycle (test, start, restart) and directly-run scripts.

As of npm@2.0.0, you can use custom arguments when executing scripts. The special option -- is used by getopt to delimit the end of the options. npm will pass all the arguments after the -- directly to your script:

npm run test -- --grep="pattern"

The arguments will only be passed to the script specified after npm run and not to any pre or post script.

The env script is a special built-in command that can be used to list environment variables that will be available to the script at runtime. If an "env" command is defined in your package it will take precedence over the built-in.

In addition to the shell's pre-existing PATH, npm run adds node_modules/.bin to the PATH provided to scripts. Any binaries provided by locally-installed dependencies can be used without the node_modules/.bin prefix. For example, if there is a devDependency on tap in your package, you should write:

"scripts": {"test": "tap test/\*.js"}

instead of "scripts": {"test": "node_modules/.bin/tap test/\*.js"} to run your tests.

npm run sets the NODE environment variable to the node executable with which npm is executed. Also, if the --scripts-prepend-node-path is passed, the directory within which node resides is added to the PATH. If --scripts-prepend-node-path=auto is passed (which has been the default in npm v3), this is only performed when that node executable is not found in the PATH.

If you try to run a script without having a node_modules directory and it fails, you will be given a warning to run npm install, just in case you've forgotten.

Last modified December 16, 2016           Found a typo? Send a pull request!

npm-search

npm search [-l|--long] [--json] [--parseable] [--no-description] [search terms ...]

aliases: s, se, find

Search the registry for packages matching the search terms. npm search performs a linear, incremental, lexically-ordered search through package metadata for all files in the registry. If color is enabled, it will further highlight the matches in the results.

Additionally, using the --searchopts and --searchexclude options paired with more search terms will respectively include and exclude further patterns. The main difference between --searchopts and the standard search terms is that the former does not highlight results in the output and can be used for more fine-grained filtering. Additionally, both of these can be added to .npmrc for default search filtering behavior.

Search also allows targeting of maintainers in search results, by prefixing their npm username with =.

If a term starts with /, then it's interpreted as a regular expression and supports standard JavaScript RegExp syntax. A trailing / will be ignored in this case. (Note that many regular expression characters must be escaped or quoted in most shells.)

Used as --no-description, disables search matching in package descriptions and suppresses display of that field in results.

Output search results as a JSON array.

Output search results as lines with tab-separated columns.

Display full package descriptions and other long text across multiple lines. When disabled (default) search results are truncated to fit neatly on a single line. Modules with extremely long names will fall on multiple lines.

Space-separated options that are always passed to search.

Space-separated options that limit the results from search.

The age of the cache, in seconds, before another registry request is made.

Search the specified registry for modules. If you have configured npm to point to a different default registry, such as your internal private module repository, npm search will default to that registry when searching. Pass a different registry url such as the default above in order to override this setting.

Last modified December 16, 2016           Found a typo? Send a pull request!

npm-shrinkwrap

npm shrinkwrap

This command locks down the versions of a package's dependencies so that you can control exactly which versions of each dependency will be used when your package is installed. The package.json file is still required if you want to use npm install.

By default, npm install recursively installs the target's dependencies (as specified in package.json), choosing the latest available version that satisfies the dependency's semver pattern. In some situations, particularly when shipping software where each change is tightly managed, it's desirable to fully specify each version of each dependency recursively so that subsequent builds and deploys do not inadvertently pick up newer versions of a dependency that satisfy the semver pattern. Specifying specific semver patterns in each dependency's package.json would facilitate this, but that's not always possible or desirable, as when another author owns the npm package. It's also possible to check dependencies directly into source control, but that may be undesirable for other reasons.

As an example, consider package A:

{
  "name": "A",
  "version": "0.1.0",
  "dependencies": {
    "B": "<0.1.0"
  }
}

package B:

{
  "name": "B",
  "version": "0.0.1",
  "dependencies": {
    "C": "<0.1.0"
  }
}

and package C:

{
  "name": "C",
  "version": "0.0.1"
}

If these are the only versions of A, B, and C available in the registry, then a normal npm install A will install:

A@0.1.0
`-- B@0.0.1
    `-- C@0.0.1

However, if B@0.0.2 is published, then a fresh npm install A will install:

A@0.1.0
`-- B@0.0.2
    `-- C@0.0.1

assuming the new version did not modify B's dependencies. Of course, the new version of B could include a new version of C and any number of new dependencies. If such changes are undesirable, the author of A could specify a dependency on B@0.0.1. However, if A's author and B's author are not the same person, there's no way for A's author to say that he or she does not want to pull in newly published versions of C when B hasn't changed at all.

In this case, A's author can run

npm shrinkwrap

This generates npm-shrinkwrap.json, which will look something like this:

{
  "name": "A",
  "version": "0.1.0",
  "dependencies": {
    "B": {
      "version": "0.0.1",
      "from": "B@^0.0.1",
      "resolved": "https://registry.npmjs.org/B/-/B-0.0.1.tgz",
      "dependencies": {
        "C": {
          "version": "0.0.1",
          "from": "org/C#v0.0.1",
          "resolved": "git://github.com/org/C.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
        }
      }
    }
  }
}

The shrinkwrap command has locked down the dependencies based on what's currently installed in node_modules. The installation behavior is changed to:

  1. The module tree described by the shrinkwrap is reproduced. This means reproducing the structure described in the file, using the specific files referenced in "resolved" if available, falling back to normal package resolution using "version" if one isn't.

  2. The tree is walked and any missing dependencies are installed in the usual fashion.

If preshrinkwrap, shrinkwrap or postshrinkwrap are in the scripts property of the package.json, they will be executed by running npm shrinkwrap. preshrinkwrap and shrinkwrap are executed before the shrinkwrap, postshrinkwrap is executed afterwards. For example to run some postprocessing on the generated file:

"scripts": { "postshrinkwrap": "node fix-shrinkwrap.js" }

Using a shrinkwrapped package is no different than using any other package: you can npm install it by hand, or add a dependency to your package.json file and npm install it.

To shrinkwrap an existing package:

  1. Run npm install in the package root to install the current versions of all dependencies.
  2. Validate that the package works as expected with these versions.
  3. Run npm shrinkwrap, add npm-shrinkwrap.json to git, and publish your package.

To add or update a dependency in a shrinkwrapped package:

  1. Run npm install in the package root to install the current versions of all dependencies.
  2. Add or update dependencies. npm install --save or npm install --save-dev each new or updated package individually to update the package.json and the shrinkwrap. Note that they must be explicitly named in order to be installed: running npm install with no arguments will merely reproduce the existing shrinkwrap.
  3. Validate that the package works as expected with the new dependencies.
  4. Commit the new npm-shrinkwrap.json, and publish your package.

You can use npm-outdated to view dependencies with newer versions available.

A shrinkwrap file must be consistent with the package's package.json file. npm shrinkwrap will fail if required dependencies are not already installed, since that would result in a shrinkwrap that wouldn't actually work. Similarly, the command will fail if there are extraneous packages (not referenced by package.json), since that would indicate that package.json is not correct.

Starting with npm v4.0.1, devDependencies are included when you run npm shrinkwrap and follow the usual rules as to when they're installed. As of npm v3.10.8, if you run npm install --only=production or npm install --production with a shrinkwrap including your development dependencies they won't be installed. Similarly, if the environment variable NODE_ENV is production then they won't be installed. If you need compatibility with versions of npm prior to v3.10.8 or otherwise don't want them in your shrinkwrap you can exclude development dependencies with: npm shrinkwrap --only=prod or npm shrinkwrap --production.

If shrinkwrapped package A depends on shrinkwrapped package B, B's shrinkwrap will not be used as part of the installation of A. However, because A's shrinkwrap is constructed from a valid installation of B and recursively specifies all dependencies, the contents of B's shrinkwrap will implicitly be included in A's shrinkwrap.

If you wish to lock down the specific bytes included in a package, for example to have 100% confidence in being able to reproduce a deployment or build, then you ought to check your dependencies into source control, or pursue some other mechanism that can verify contents rather than versions.

Last modified January 13, 2017           Found a typo? Send a pull request!

npm-star

npm star [<pkg>...]
npm unstar [<pkg>...]

"Starring" a package means that you have some interest in it. It's a vaguely positive way to show that you care.

"Unstarring" is the same thing, but in reverse.

It's a boolean thing. Starring repeatedly has no additional effect.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-stars

npm stars [<user>]

If you have starred a lot of neat things and want to find them again quickly this command lets you do just that.

You may also want to see your friend's favorite packages, in this case you will most certainly enjoy this command.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-start

npm start [-- <args>]

This runs an arbitrary command specified in the package's "start" property of its "scripts" object. If no "start" property is specified on the "scripts" object, it will run node server.js.

As of npm@2.0.0, you can use custom arguments when executing scripts. Refer to npm-run-script for more details.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-stop

npm stop [-- <args>]

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

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-team

npm team create <scope:team>
npm team destroy <scope:team>

npm team add <scope:team> <user>
npm team rm <scope:team> <user>

npm team ls <scope>|<scope:team>

npm team edit <scope:team>

Used to manage teams in organizations, and change team memberships. Does not handle permissions for packages.

Teams must always be fully qualified with the organization/scope they belong to when operating on them, separated by a colon (:). That is, if you have a developers team on a foo organization, you must always refer to that team as foo:developers in these commands.

npm team always operates directly on the current registry, configurable from the command line using --registry=<registry url>.

In order to create teams and manage team membership, you must be a team admin under the given organization. Listing teams and team memberships may be done by any member of the organizations.

Organization creation and management of team admins and organization members is done through the website, not the npm CLI.

To use teams to manage permissions on packages belonging to your organization, use the npm access command to grant or revoke the appropriate permissions.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-test

  npm test [-- <args>]

  aliases: t, tst

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

Last modified December 16, 2016           Found a typo? Send a pull request!

npm-uninstall

npm uninstall [<@scope>/]<pkg>[@<version>]... [-S|--save|-D|--save-dev|-O|--save-optional]

aliases: remove, rm, r, un, unlink

This uninstalls a package, completely removing everything npm installed on its behalf.

Example:

npm uninstall sax

In global mode (ie, with -g or --global appended to the command), it uninstalls the current package context as a global package.

npm uninstall takes 3 exclusive, optional flags which save or update the package version in your main package.json:

Further, if you have an npm-shrinkwrap.json then it will be updated as well.

Scope is optional and follows the usual rules for npm-scope.

Examples:

npm uninstall sax --save
npm uninstall @myorg/privatepackage --save
npm uninstall node-tap --save-dev
npm uninstall dtrace-provider --save-optional

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-unpublish

npm unpublish [<@scope>/]<pkg>[@<version>]

It is generally considered bad behavior to remove versions of a library that others are depending on!

Consider using the deprecate command instead, if your intent is to encourage users to upgrade.

There is plenty of room on the registry.

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.

Even if a package version is unpublished, that specific name and version combination can never be reused. In order to publish the package again, a new version number must be used.

The scope is optional and follows the usual rules for npm-scope.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-update

npm update [-g] [<pkg>...]

aliases: up, upgrade

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

It will also install missing packages. As with all commands that install packages, the --dev flag will cause devDependencies to be processed as well.

If the -g flag is specified, this command will update globally installed packages.

If no package name is specified, all packages in the specified location (global or local) will be updated.

As of npm@2.6.1, the npm update will only inspect top-level packages. Prior versions of npm would also recursively inspect all dependencies. To get the old behavior, use npm --depth 9999 update.

IMPORTANT VERSION NOTE: these examples assume npm@2.6.1 or later. For older versions of npm, you must specify --depth 0 to get the behavior described below.

For the examples below, assume that the current package is app and it depends on dependencies, dep1 (dep2, .. etc.). The published versions of dep1 are:

{
  "dist-tags": { "latest": "1.2.2" },
  "versions": [
    "1.2.2",
    "1.2.1",
    "1.2.0",
    "1.1.2",
    "1.1.1",
    "1.0.0",
    "0.4.1",
    "0.4.0",
    "0.2.0"
  ]
}

If app's package.json contains:

"dependencies": {
  "dep1": "^1.1.1"
}

Then npm update will install dep1@1.2.2, because 1.2.2 is latest and 1.2.2 satisfies ^1.1.1.

However, if app's package.json contains:

"dependencies": {
  "dep1": "~1.1.1"
}

In this case, running npm update will install dep1@1.1.2. Even though the latest tag points to 1.2.2, this version does not satisfy ~1.1.1, which is equivalent to >=1.1.1 <1.2.0. So the highest-sorting version that satisfies ~1.1.1 is used, which is 1.1.2.

Suppose app has a caret dependency on a version below 1.0.0, for example:

"dependencies": {
  "dep1": "^0.2.0"
}

npm update will install dep1@0.2.0, because there are no other versions which satisfy ^0.2.0.

If the dependence were on ^0.4.0:

"dependencies": {
  "dep1": "^0.4.0"
}

Then npm update will install dep1@0.4.1, because that is the highest-sorting version that satisfies ^0.4.0 (>= 0.4.0 <0.5.0)

When you want to update a package and save the new version as the minimum required dependency in package.json, you can use npm update -S or npm update --save. For example if package.json contains:

"dependencies": {
  "dep1": "^1.1.1"
}

Then npm update --save will install dep1@1.2.2 (i.e., latest), and package.json will be modified:

"dependencies": {
  "dep1": "^1.2.2"
}

Note that npm will only write an updated version to package.json if it installs a new package.

npm update -g will apply the update action to each globally installed package that is outdated -- that is, has a version that is different from latest.

NOTE: If a package has been upgraded to a version newer than latest, it will be downgraded.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-version

npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]

'npm [-v | --version]' to print npm version
'npm view <pkg> version' to view a package's published version
'npm ls' to inspect current package/dependency versions

Run this in a package directory to bump the version and write the new data back to package.json and, if present, npm-shrinkwrap.json.

The newversion argument should be a valid semver string, a valid second argument to semver.inc (one of patch, minor, major, prepatch, preminor, premajor, prerelease), or from-git. In the second case, the existing version will be incremented by 1 in the specified field. from-git will try to read the latest git tag, and use that as the new npm version.

If run in a git repo, it will also create a version commit and tag. This behavior is controlled by git-tag-version (see below), and can be disabled on the command line by running npm --no-git-tag-version version. It will fail if the working directory is not clean, unless the -f or --force flag is set.

If supplied with -m or --message config option, npm will use it as a commit message when creating a version commit. If the message config contains %s then that will be replaced with the resulting version number. For example:

npm version patch -m "Upgrade to %s for reasons"

If the sign-git-tag config is set, then the tag will be signed using the -s flag to git. Note that you must have a default GPG key set up in your git config for this to work properly. For example:

$ npm config set sign-git-tag true
$ npm version patch

You need a passphrase to unlock the secret key for
user: "isaacs (http://blog.izs.me/) <i@izs.me>"
2048-bit RSA key, ID 6C481CF6, created 2010-08-31

Enter passphrase:

If preversion, version, or postversion are in the scripts property of the package.json, they will be executed as part of running npm version.

The exact order of execution is as follows:

  1. Check to make sure the git working directory is clean before we get started. Your scripts may add files to the commit in future steps. This step is skipped if the --force flag is set.
  2. Run the preversion script. These scripts have access to the old version in package.json. A typical use would be running your full test suite before deploying. Any files you want added to the commit should be explicitly added using git add.
  3. Bump version in package.json as requested (patch, minor, major, etc).
  4. Run the version script. These scripts have access to the new version in package.json (so they can incorporate it into file headers in generated files for example). Again, scripts should explicitly add generated files to the commit using git add.
  5. Commit and tag.
  6. Run the postversion script. Use it to clean up the file system or automatically push the commit and/or tag.

Take the following example:

"scripts": {
  "preversion": "npm test",
  "version": "npm run build && git add -A dist",
  "postversion": "git push && git push --tags && rm -rf build/temp"
}

This runs all your tests, and proceeds only if they pass. Then runs your build script, and adds everything in the dist directory to the commit. After the commit, it pushes the new commit and tag up to the server, and deletes the build/temp directory.

Commit and tag the version change.

Pass the -s flag to git to sign the tag.

Note that you must have a default GPG key set up in your git config for this to work properly.

Last modified January 13, 2017           Found a typo? Send a pull request!

npm-view

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

aliases: info, show, v

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 fields 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 example, 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 package.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

To show the connect package version history, you can do this:

npm view connect versions

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 field is an object, it will be output as a JavaScript object literal.

If the --json flag is given, the outputted fields will be JSON.

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.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-whoami

npm whoami [--registry <registry>]

Print the username config to standard output.

Last modified December 03, 2016           Found a typo? Send a pull request!

npm-folders

npm puts various things on your computer. That's its job.

This document will tell you what it puts where.

The prefix config defaults to the location where node is installed. On most systems, this is /usr/local. 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.

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

Scoped packages are installed the same way, except they are grouped together in a sub-folder of the relevant node_modules folder with the name of that scope prefix by the @ symbol, e.g. npm install @myorg/package would place the package in {prefix}/node_modules/@myorg/package. See scope for more details.

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

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

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.

See npm-cache. Cache files are stored in ~/.npm on Posix, or ~/npm-cache on Windows.

This is controlled by the cache configuration param.

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.

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

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

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.

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

Last modified December 03, 2016           Found a typo? Send a pull request!

npmrc

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.

The four relevant files are:

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.

Array values are specified by adding "[]" after the key name. For example:

key[] = "first value"
key[] = "second value"

Lines in .npmrc files are interpreted as comments when they begin with a ; or # character. .npmrc files are parsed by npm/ini, which specifies this comment syntax.

For example:

# last modified: 01 Jan 2016
; Set a new registry for a scoped package
@myscope:registry=https://mycustomregistry.example.org

When working locally in a project, a .npmrc file in the root of the project (ie, a sibling of node_modules and package.json) will set config values specific to this project.

Note that this only applies to the root of the project that you're running npm in. It has no effect when your module is published. For example, you can't publish a module that forces itself to install globally, or in a different location.

Additionally, this file is not read in global mode, such as when running npm install -g.

$HOME/.npmrc (or the userconfig param, if set in the environment or on the command line)

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

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.

Last modified January 13, 2017           Found a typo? Send a pull request!

package.json

This document is all you need to know about what's required in your package.json file. It must be actual JSON, not just a JavaScript object literal.

A lot of the behavior described in this document is affected by the config settings described in npm-config.

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

Some tips:

A name can be optionally prefixed by a scope, e.g. @myorg/mypackage. See npm-scope for more detail.

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

More on version numbers and ranges at semver.

Put a description in it. It's a string. This helps people discover your package, as it's listed in npm search.

Put keywords in it. It's an array of strings. This helps people discover your package as it's listed in npm search.

The url to the project homepage.

The url to your project's issue tracker and / or the email address to which issues should be reported. These are helpful for people who encounter issues with your package.

It should look like this:

{ "url" : "https://github.com/owner/project/issues"
, "email" : "project@hostname.com"
}

You can specify either one or both values. If you want to provide only a url, you can specify the value for "bugs" as a simple string instead of an object.

If a url is provided, it will be used by the npm bugs command.

You should specify a license for your package so that people know how they are permitted to use it, and any restrictions you're placing on it.

If you're using a common license such as BSD-2-Clause or MIT, add a current SPDX license identifier for the license you're using, like this:

{ "license" : "BSD-3-Clause" }

You can check the full list of SPDX license IDs. Ideally you should pick one that is OSI approved.

If your package is licensed under multiple common licenses, use an SPDX license expression syntax version 2.0 string, like this:

{ "license" : "(ISC OR GPL-3.0)" }

If you are using a license that hasn't been assigned an SPDX identifier, or if you are using a custom license, use a string value like this one:

{ "license" : "SEE LICENSE IN <filename>" }

Then include a file named <filename> at the top level of the package.

Some old packages used license objects or a "licenses" property containing an array of license objects:

// Not valid metadata
{ "license" :
  { "type" : "ISC"
  , "url" : "https://opensource.org/licenses/ISC"
  }
}

// Not valid metadata
{ "licenses" :
  [
    { "type": "MIT"
    , "url": "https://www.opensource.org/licenses/mit-license.php"
    }
  , { "type": "Apache-2.0"
    , "url": "https://opensource.org/licenses/apache2.0.php"
    }
  ]
}

Those styles are now deprecated. Instead, use SPDX expressions, like this:

{ "license": "ISC" }

{ "license": "(MIT OR Apache-2.0)" }

Finally, if you do not wish to grant others the right to use a private or unpublished package under any terms:

{ "license": "UNLICENSED"}

Consider also setting "private": true to prevent accidental publication.

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.

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 or in subdirectories, 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.

Certain files are always included, regardless of settings:

README, CHANGES, LICENSE & NOTICE can have any case and extension.

Conversely, some files are always ignored:

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.

A lot of packages have one or more executable files that they'd like to install into the PATH. npm makes this pretty easy (in fact, it uses this feature to install the "npm" executable.)

To use this, supply a bin field in your package.json which is a map of command name to local file name. On install, npm will symlink that file into prefix/bin for global installs, or ./node_modules/.bin/ for local installs.

For example, myapp could have this:

{ "bin" : { "myapp" : "./cli.js" } }

So, when you install myapp, it'll create a symlink from the cli.js script to /usr/local/bin/myapp.

If you have a single executable, and its name should be the name of the package, then you can just supply it as a string. For example:

{ "name": "my-program"
, "version": "1.2.5"
, "bin": "./path/to/program" }

would be the same as this:

{ "name": "my-program"
, "version": "1.2.5"
, "bin" : { "my-program" : "./path/to/program" } }

Please make sure that your file(s) referenced in bin starts with #!/usr/bin/env node, otherwise the scripts are started without the node executable!

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

The CommonJS Packages spec details a few ways that you can indicate the structure of your package using a directories object. 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.

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.

If you specify a bin directory in directories.bin, all the files in that folder will be added.

Because of the way the bin directive works, specifying both a bin path and setting directories.bin is an error. If you want to specify individual files, use bin, and for all the files in an existing bin directory, use directories.bin.

A folder that is full of man pages. Sugar to generate a "man" array by walking the folder.

Put markdown files in here. Eventually, these will be displayed nicely, maybe, someday.

Put example scripts in here. Someday, it might be exposed in some clever way.

Put your tests in here. It is currently not exposed, but it might be in the future.

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" : "https://github.com/npm/npm.git"
  }

"repository" :
  { "type" : "svn"
  , "url" : "https://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.

For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use the same shortcut syntax you use for npm install:

"repository": "npm/npm"

"repository": "gist:11081aaa281"

"repository": "bitbucket:example/repo"

"repository": "gitlab:another/repo"

The "scripts" property is a dictionary containing script commands that are run at various times in the lifecycle of your package. The key is the lifecycle event, and the value is the command to run at that point.

See npm-scripts to find out more about writing package scripts.

A "config" object can be used to set configuration parameters used in package scripts that persist across upgrades. For instance, if a package had the following:

{ "name" : "foo"
, "config" : { "port" : "8080" } }

and then had a "start" command that then referenced the npm_package_config_port environment variable, then the user could override that by doing npm config set foo:port 8001.

See npm-config and npm-scripts for more on package configs.

Dependencies are specified in a simple object that maps a package name to a version range. The version range is a string which has one or more space-separated descriptors. Dependencies can also be identified with a tarball or git URL.

Please do not put test harnesses or transpilers in your dependencies object. See devDependencies, below.

See semver for more details about specifying version ranges.

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"
  , "lat" : "latest"
  , "dyl" : "file:../dyl"
  }
}

You may specify a tarball URL in place of a version range.

This tarball will be downloaded and installed locally to your package at install time.

Git urls can be of the form:

git://github.com/user/project.git#commit-ish
git+ssh://user@hostname:project.git#commit-ish
git+ssh://user@hostname/project.git#commit-ish
git+http://user@hostname/project/blah.git#commit-ish
git+https://user@hostname/project/blah.git#commit-ish

The commit-ish can be any tag, sha, or branch which can be supplied as an argument to git checkout. The default is master.

As of version 1.1.65, you can refer to GitHub urls as just "foo": "user/foo-project". Just as with git URLs, a commit-ish suffix can be included. For example:

{
  "name": "foo",
  "version": "0.0.0",
  "dependencies": {
    "express": "expressjs/express",
    "mocha": "mochajs/mocha#4727d357ea",
    "module": "user/repo#feature\/branch"
  }
}

As of version 2.0.0 you can provide a path to a local directory that contains a package. Local paths can be saved using npm install -S or npm install --save, using any of these forms:

../foo/bar
~/foo/bar
./foo/bar
/foo/bar

in which case they will be normalized to a relative path and added to your package.json. For example:

{
  "name": "baz",
  "dependencies": {
    "bar": "file:../foo/bar"
  }
}

This feature is helpful for local offline development and creating tests that require npm installing where you don't want to hit an external server, but should not be used when publishing packages to the public registry.

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 map these additional items in a devDependencies object.

These things will be installed when doing npm link or npm install from the root of a package, and can be managed like any other npm configuration param. See npm-config for more on the topic.

For build steps that are not platform-specific, such as compiling CoffeeScript or other languages to JavaScript, use the prepare script to do this, and make the required package a devDependency.

For example:

{ "name": "ethopia-waza",
  "description": "a delightfully fruity coffee varietal",
  "version": "1.2.3",
  "devDependencies": {
    "coffee-script": "~1.6.3"
  },
  "scripts": {
    "prepare": "coffee -o lib/ -c src/waza.coffee"
  },
  "main": "lib/waza.js"
}

The prepare script will be run before publishing, so that users can consume the functionality without requiring them to compile it themselves. In dev mode (ie, locally running npm install), it'll run this script as well, so that you can test it easily.

In some cases, you want to express the compatibility of your package with a host tool or library, while not necessarily doing a require of this host. This is usually referred to as a plugin. Notably, your module may be exposing a specific interface, expected and specified by the host documentation.

For example:

{
  "name": "tea-latte",
  "version": "1.3.5",
  "peerDependencies": {
    "tea": "2.x"
  }
}

This ensures your package tea-latte can be installed along with the second major version of the host package tea only. npm install tea-latte could possibly yield the following dependency graph:

├── tea-latte@1.3.5
└── tea@2.2.0

NOTE: npm versions 1 and 2 will automatically install peerDependencies if they are not explicitly depended upon higher in the dependency tree. In the next major version of npm (npm@3), this will no longer be the case. You will receive a warning that the peerDependency is not installed instead. The behavior in npms 1 & 2 was frequently confusing and could easily put you into dependency hell, a situation that npm is designed to avoid as much as possible.

Trying to install another plugin with a conflicting requirement will cause an error. For this reason, make sure your plugin requirement is as broad as possible, and not to lock it down to specific patch versions.

Assuming the host complies with semver, only changes in the host package's major version will break your plugin. Thus, if you've worked with every 1.x version of the host package, use "^1.0" or "1.x" to express this. If you depend on features introduced in 1.5.2, use ">= 1.5.2 < 2".

This defines an array of package names that will be bundled when publishing the package.

In cases where you need to preserve npm packages locally or have them available through a single file download, you can bundle the packages in a tarball file by specifying the package names in the bundledDependencies array and executing npm pack.

For example:

If we define a package.json like this:

{
  "name": "awesome-web-framework",
  "version": "1.0.0",
  "bundledDependencies": [
    'renderized', 'super-streams'
  ]
}

we can obtain awesome-web-framework-1.0.0.tgz file by running npm pack. This file contains the dependencies renderized and super-streams which can be installed in a new project by executing npm install awesome-web-framework-1.0.0.tgz.

If this is spelled "bundleDependencies", then that is also honored.

If a dependency can be used, but you would like npm to proceed if it cannot be found or fails to install, then you may put it in the optionalDependencies object. This is a map of package name to version or url, just like the dependencies object. The difference is that build failures do not cause installation to fail.

It is still your program's responsibility to handle the lack of the dependency. For example, something like this:

try {
  var foo = require('foo')
  var fooVersion = require('foo/package.json').version
} catch (er) {
  foo = null
}
if ( notGoodFooVersion(fooVersion) ) {
  foo = null
}

// .. then later in your program ..

if (foo) {
  foo.doFooThings()
}

Entries in optionalDependencies will override entries of the same name in dependencies, so it's usually best to only put in one place.

You can specify the version of node that your stuff works on:

{ "engines" : { "node" : ">=0.10.3 <0.12" } }

And, like with dependencies, if you don't specify the version (or if you specify "*" as the version), then any version of node will do.

If you specify an "engines" field, then npm will require that "node" be somewhere on that list. If "engines" is omitted, then npm will just assume that it works on node.

You can also use the "engines" field to specify which versions of npm are capable of properly installing your program. For example:

{ "engines" : { "npm" : "~1.0.20" } }

Unless the user has set the engine-strict config flag, this field is advisory only will produce warnings when your package is installed as a dependency.

This feature was removed in npm 3.0.0

Prior to npm 3.0.0, this feature was used to treat this package as if the user had set engine-strict. It is no longer used.

You can specify which operating systems your module will run on:

"os" : [ "darwin", "linux" ]

You can also blacklist instead of whitelist operating systems, just prepend the blacklisted os with a '!':

"os" : [ "!win32" ]

The host operating system is determined by process.platform

It is allowed to both blacklist, and whitelist, although there isn't any good reason to do this.

If your code only runs on certain cpu architectures, you can specify which ones.

"cpu" : [ "x64", "ia32" ]

Like the os option, you can also blacklist architectures:

"cpu" : [ "!arm", "!mips" ]

The host architecture is determined by process.arch

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.

If you set "private": true in your package.json, then npm will refuse to publish it.

This is a way to prevent accidental publication of private repositories. If you would like to ensure that a given package is only ever published to a specific registry (for example, an internal registry), then use the publishConfig dictionary described below to override the registry config param at publish-time.

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, registry or access, so that you can ensure that a given package is not tagged with "latest", published to the global public registry or that a scoped module is private by default.

Any config values can be overridden, but of course only "tag", "registry" and "access" probably matter for the purposes of publishing.

See npm-config to see the list of config options that can be overridden.

npm will default some values based on package contents.

Last modified January 26, 2017           Found a typo? Send a pull request!

About npm

npm is lots of things.

npm, Inc. is a company co-founded in 2014 by npm's creator, Isaac Z. Schlueter, along with Laurie Voss and Rod Boothby.

npm, Inc. is dedicated to the long term success of the JavaScript community, which includes the success of the open-source Node.js and npm projects.

At npm, Inc. we do three things to support this goal:

  1. Run the open source registry as a free service.
  2. Build tools and operate services that support the secure use of packages in a private or enterprise context.
  3. Build innovative new tools and services for the developer community.

npm's mission is to take Open Source development to entirely new places. When everyone else is adding force, we work to reduce friction.

npm is not a typical product, and we are not a typical "work hard/play hard" startup. We are responsible adults with diverse backgrounds and interests, who take our careers and our lives seriously. We believe that the best way to iterate towards success is by taking care of ourselves, our families, our users, and one another. We aim for a sustainable approach to work and life, because that is the best way to maximize long-term speed, while retaining clarity of vision. Compassion is our strategy.

Our offices are in downtown Oakland, California.

You can reach us for support or any other questions via our contact form or at npm@npmjs.com.

Last modified February 11, 2017           Found a typo? Send a pull request!

Nice People Matter: npm is hiring

If you would like to work with us and have skills you think would be helpful, please send an email with evidence of your experience (like your resume, or links to LinkedIn/GitHub/wherever) to jobs@npmjs.com.

We’d like to hear from you.

If you're currently in full-time education (class of 2016 or 2017) and looking for a summer internship with an open-source project that can also pay you, we're happy to say that we can offer you a place at npm in partnership with our investors, as part of the True Entrepreneur Corps program.

We are looking primarily for enthusiasm and intellectual curiosity, but any experience with JavaScript and especially Node.js is obviously a big advantage.

You'll be working on the open-source npm project itself, so your work will be code-reviewed by the same people who run the project, your commits will immediately benefit tens of thousands of active users, and will also be publicly verifiable by future employers.

Last year's intern, Faiq, wrote about what he learned on TEC's blog and also had this to say:

Imagine working at a place with some of the best and kindest engineers, getting paid to write open source code, and being immersed in one of the most diverse developer communities ever. It sounds too good to be true, doesn't it? When you get a chance to work at npm, you'll be doing exactly that. Day to day, you'll get to work on challenging problems that push your limits as an engineer. You'll run into problems that'll seem impossible at first, but by the end of your internship will seem like a piece of cake! This internship is one of the most unique opportunities you'll get, so definitely give it a shot and apply!

Faiq worked on our website and search. Even after leaving npm, Faiq continues to be involved and has even committed to npm core. You can expect a similar range of opportunities, depending on your interests.

If you're interested, please send a brief email introducing yourself as well as a PDF or Google doc of your resume to jobs@npmjs.com and include the word "internship" in your subject line. The internship is based out of our offices in Oakland, California. You must be part of the graduating class of 2016 or 2017 and legally able to work in the United States; we are not currently able to sponsor visa applications.

npm is the package manager for JavaScript. The team is small, and growing quickly. If you join us, you will see the company grow through numerous changes, and take a bunch of different roles.

npm’s mission is to take Open Source development to entirely new places. When everyone else is adding force, we work to reduce friction.

npm is not a typical product, and we are not a typical early-stage “work hard/play hard” startup. We are responsible adults with diverse backgrounds and interests, who take our careers and our lives seriously. We believe that the best way to iterate towards success is by taking care of ourselves, our families, our users, and one another. We aim for a sustainable approach to work and life, because that is the best way to maximize long-term speed, while retaining clarity of vision. Compassion is our strategy.

Our offices are in downtown Oakland, California. We offer very competitive salaries, meaningful equity, and generous health, dental and vision benefits. We love it when you represent us at conferences.

Last modified February 11, 2017           Found a typo? Send a pull request!

npm Private Modules

Private modules are ordinary npm packages that only you, and people you select, can view, install, and publish. You publish them in your namespace or your team's namespace, just by giving them a name in package.json:

{
  "name": "@myuser/mypackage"
}

You publish them with npm publish, just like any other package, and you install them by name:

npm install @myuser/mypackage

Once installed, use them by requiring them by name, just like any package:

var mypackage = require('@myuser/mypackage');

You re-use code between projects. npm and the registry make it really easy to share small modules of useful code with the world. But sometimes the code in that package is private, or sensitive, or just too specific to your needs for you to want to publish it to the public registry. Private packages are great for this.

You work in a team, or you work for clients. You want to be able to easily share your work, with the dependency management and version management that npm provides. By making it easy and granular to select who can see, install and publish packages, private packages make this easy.

Last modified February 11, 2017           Found a typo? Send a pull request!

Security

Need to report a security vulnerability? Please contact us or email security@npmjs.com.

Our engineering team is well-versed in security best practices.

Our software is regularly audited by reputable third-party security firms, currently Lift Security.

We maintain a recent, production-ready OS that is regularly patched with the latest security fixes.

Our servers live behind a firewall that only allows expected traffic on limited ports.

Our services are fronted by a CDN that allows for protection from Distributed Denial of Service (DDoS) attacks.

All private data exchanged with npm from the command line and via the website is passed over encrypted connections (HTTPS and SSL).

npm's servers are hosted on Amazon Web Services. Physical security is maximized because nobody knows exactly which physical servers host our virtual ones.

All registry data and binaries are stored in multiple redundant, physically separate locations. All binaries and metadata are backed up to a third-party, off-site location. These backups are encrypted.

Employees of npm Inc. have access to package metadata and binaries for support and debugging purposes. Employees do not have access to the password for your npm account, which is always encrypted.

For more information about how we handle your personal data, you may wish to review our privacy policy.

For firms interested in greater levels of physical and operational security, npm Enterprise is a self-hosted version of the npm Registry that allows total control of the operation and policies of the registry.

If you have further questions or concerns about npm security, please contact us.

Last modified February 11, 2017           Found a typo? Send a pull request!

npm Weekly

Did you miss one? Check out the npm weekly archive.

Last modified February 11, 2017           Found a typo? Send a pull request!

Getting Started

How npm works

Private Modules

Organizations

Using npm

CLI Commands

Configuring npm

npm Enterprise

View All On One Page