npmjs.com

All Docs

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:

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, 2016           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 November 29, 2015           Found a typo? Send a pull request!

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.

Last modified December 29, 2015           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:

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 December 29, 2015           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 December 29, 2015           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 nodejs.org. 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.

sudo npm install npm -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 January 19, 2016           Found a typo? Send a pull request!

npm v2 Dependency Resolution

Example - Explore on Github

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 December 29, 2015           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/
  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 January 28, 2016           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 two options:

  1. Change the permission to npm's default directory.
  2. Change npm's default directory to another directory.

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.

  1. 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 npm install -g jshint

Last modified February 17, 2016           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:

Example - Explore on Github

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 December 30, 2015           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 December 29, 2015           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 run 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 December 29, 2015           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 December 30, 2015           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][#removing-the-developers-team], by default it acts as a "catch-all" team. This means:

The effects of deleting the team are [covered below][#removing-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. 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 December 29, 2015           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 December 30, 2015           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>
> npm team ls <org> <user>

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

Last modified December 29, 2015           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 questionaire that will conclude with the creation of a package.json in the directory you initiated the command.

The --yes init flag

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.

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 --save and --save-dev install flags

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, 2016           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 December 29, 2015           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 December 29, 2015           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 December 29, 2015           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

Last modified December 29, 2015           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 January 08, 2016           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 December 29, 2015           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 December 29, 2015           Found a typo? Send a pull request!

Updating global packages

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

npm install -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 November 29, 2015           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 December 29, 2015           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 December 29, 2015           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.

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 January 19, 2016           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 December 29, 2015           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 December 29, 2015           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 January 19, 2016           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 January 11, 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 January 08, 2016           Found a typo? Send a pull request!

npm-adduser

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

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. 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. 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 08, 2016           Found a typo? Send a pull request!

npm-bin

npm bin [-g|--global]

Print the folder where npm will install executables.

Last modified January 08, 2016           Found a typo? Send a pull request!

npm-bugs

npm bugs [<pkgname>]

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 January 08, 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 January 08, 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 January 08, 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>]

Used to add, list, or clear 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 08, 2016           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 January 08, 2016           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 January 08, 2016           Found a typo? Send a pull request!

npm Code of Conduct

npm exists to facilitate sharing code, by making it easy for JavaScript module developers to publish and distribute packages.

npm is a piece of technology, but more importantly, it is a community.

We believe that our mission is best served in an environment that is friendly, safe, and accepting; free from intimidation or harassment.

Towards this end, certain behaviors and practices will not be tolerated.

We expect all members of the npm community, including paid and unpaid agents, administrators, users, and customers of npm, Inc., to abide by this Code of Conduct at all times in all npm community venues, online and in person, and in one-on-one communications pertaining to npm affairs.

This policy covers the usage of the npm registry, as well as the npm website, npm related events, and any other services offered by or on behalf of npm, Inc. (collectively, the "Service"). It also applies to behavior in the context of the npm Open Source project communities, including but not limited to public GitHub repositories, IRC channels, social media, mailing lists, and public events.

This Code of Conduct is in addition to, and does not in any way nullify or invalidate, any other terms or conditions related to use of the Service.

The definitions of various subjective terms such as "discriminatory", "hateful", or "confusing" will be decided at the sole discretion of the npm abuse team.

We are committed to providing a friendly, safe and welcoming environment for all, regardless of gender identity, sexual orientation, ability, ethnicity, religion, age, physical appearance, body size, race, or similar personal characteristics.

We ask that you please respect that people have differences of opinion regarding technical choices, and that every design or implementation choice carries a trade-off and numerous costs. There is seldom a single right answer. A difference of technology preferences is not a license to be rude.

Disputes over package rights must be handled respectfully, according to the terms described in the npm Dispute Resolution document. There is never a good reason to be rude over package name disputes.

Any spamming, trolling, flaming, baiting, or other attention-stealing behavior is not welcome, and will not be tolerated.

Harassing other users of the Service is never tolerated, whether via public or private media.

Avoid using offensive or harassing package names, nicknames, or other identifiers that might detract from a friendly, safe, and welcoming environment for all.

Harassment includes, but is not limited to: harmful or prejudicial verbal or written comments related to gender identity, sexual orientation, ability, ethnicity, religion, age, physical appearance, body size, race, or similar personal characteristics; inappropriate use of nudity, sexual images, and/or sexually explicit language in public spaces; threats of physical or non-physical harm; deliberate intimidation, stalking or following; harassing photography or recording; sustained disruption of talks or other events; inappropriate physical contact; and unwelcome sexual attention.

Acceptable Package Content

The Service administrators reserve the right to make judgment calls about what is and isn't appropriate in published packages. These are guidelines to help you be successful in our community.

Packages published to the Service must be created using the npm command-line client, or a functionally equivalent implementation. For example, a "package" must not be a PNG or JPEG image, movie file, or text document. Using the Service as a personal general-purpose database is also not allowed for this reason. Packages should be npm packages, and nothing else.

Packages must contain some functionality. "Squatting", that is, publishing an empty package to "reserve" a name, is not allowed.

Packages must not contain illegal or infringing content. You should only publish packages or other materials to the Service if you have the right to do so. This includes complying with all software license agreements or other intellectual property restrictions. For example, redistributing an MIT-licensed module with the copyright notice removed, would not be allowed. You will be responsible for any violation of laws or others’ intellectual property rights.

Packages must not be malware. For example, a package which is designed to maliciously exploit or damage computer systems, is not allowed. However, an explicitly documented penetration testing library designed to be used for white-hat security research would most likely be fine.

Package name, description, and other visible metadata must not include abusive, inappropriate, or harassing content.

If you believe someone is harassing you or has otherwise violated this Code of Conduct, please contact us at abuse@npmjs.com to send us an abuse report. If this is the initial report of a problem, please include as much detail as possible. It is easiest for us to address issues when we have more context.

All content published to the Service, including user account credentials, is hosted at the sole discretion of the npm administrators.

Unacceptable behavior from any community member, including sponsors, employees, customers, or others with decision-making authority, will not be tolerated.

Anyone asked to stop unacceptable behavior is expected to comply immediately.

If a community member engages in unacceptable behavior, the npm administrators may take any action they deem appropriate, up to and including a temporary ban or permanent expulsion from the community without warning (and without refund in the case of a paid event or service).

If you feel you have been falsely or unfairly accused of violating this Code of Conduct, you should notify npm, Inc. We will do our best to ensure that your grievance is handled appropriately.

In general, we will choose the course of action that we judge as being most in the interest of fostering a safe and friendly community.

Please contact abuse@npmjs.com if you need to report a problem or address a grievance related to an abuse report.

You are also encouraged to contact us if you are curious about something that might be "on the line" between appropriate and inappropriate content. We are happy to provide guidance to help you be a successful part of our community.

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.

This Code of Conduct borrows heavily from the Stumptown Syndicate Citizen's Code of Conduct, and the Rust Project Code of Conduct.

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

Last modified February 02, 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]

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 January 08, 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.

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.

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.

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

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 elminate 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 is currently valid.

A client key to pass when accessing the registry.

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.

Show extended information in npm ls and npm search.

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 node version to use when checking a package's engines map.

Run tests on installation.

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.

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.

Space-separated options that are always passed to search.

Space-separated options that limit the results from search.

Indication of which field to sort search results by. Prefix with a - character to indicate reverse sort.

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 21, 2016           Found a typo? Send a pull request!

Configuring the CLI client

The client you use to interact with your npm On-Site server is the same client that you use with the public npm registry.

npm On-Site requires a 2.x or newer version of the npm client. You can get this by running:

[sudo] npm install npm -g

Once you have an up-to-date client, you can configure it to install from and publish to your private npm On-Site registry.

You can do this in one of two ways:

  1. Using On-Site for private and public packages
  2. Using On-Site for private packages only

Read about each option below.

If you want all packages, whether they are under a scope or not, to be stored in your private registry, then you should configure the npm client to use your private npm On-Site appliance as the top level registry.

To do this, first set your On-Site registry as the CLI's default registry:

npm config set registry http://myreg.mycompany.com:8080

And then authenticate against your registry without a scope:

npm login --registry=http://myreg.mycompany.com:8080

When clients are configured this way, they will always use your private npm On-Site registry as their main registry. When using npm install, it will only look in the private registry to find the package.

To make sure your On-Site instance supports this functionality, you should enable the "Read Through Cache" setting (enabled by default) in the server's admin console (https://myreg.mycompany.com:8800/settings) so that public packages are automatically mirrored from the public registry and automatically added to your registry's whitelist.

If you want to default to using the public npm registry for most packages and only use your private registry for packages under a particular scope, then you can specify that the registry should only be used for that scope.

To do so, use npm login with a registry and scope:

npm login --registry=http://myreg.mycompany.com:8080 --scope=@myco

The npm login command will prompt you for your credentials. The credentials you use should match the authentication strategy configured in the Settings of your instance's admin console (https://myreg.mycompany.com:8800/settings). By default, these will be your GitHub or GitHub Enterprise credentials.

For details on GitHub Enterprise integration, please see this page.

For details on configuring custom authentication, please see this page.

Last modified January 27, 2016           Found a typo? Send a pull request!

Custom authentication

Implementing custom authentication and authorization strategies was documented in a post on our blog.

In addition to that, our GitHub integration is open source and available on GitHub.

To enable a custom authentication strategy:

  1. on your npm On-Site server, install the plugin in /usr/local/lib/npme/data
  2. visit your npm On-Site server's admin console (http://myreg.mycompany.com:8800).
  3. choose Custom authentication.
  4. for authentication, authorization, and session provide the path to the plugin you've installed, e.g, /etc/npme/data/node_modules/my-custom-plugin

Last modified November 29, 2015           Found a typo? Send a pull request!

Customizing server configuration

You can customize the server's configuration by visiting npm On-Site's admin console (http://myreg.mycompany.com:8800).

Authentication method.

Possible values: "GitHub", "Open", "LDAP"

Configure npm On-Site to replicate from an upstream registry. This can be useful for creating backups.

Configure where npm On-Sites persistent data is stored. You may, for instance, want to store to an NFS drive that you regularly back up.

Allows npm On-Site to be configured with a corporate proxy.

Specify an alternative package URL to store in the database, rather than the IP that npm On-Site auto-detects. This is useful if you wish to place an HTTPs load-balancer in front of npm On-Site, for example:

using nginx for SSL termination

Last modified November 29, 2015           Found a typo? Send a pull request!

npm-dedupe

npm dedupe
npm 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 January 08, 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 January 08, 2016           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 January 08, 2016           Found a typo? Send a pull request!

npm-disputes

  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. Joe writes a JavaScript module foo, which is not node-specific. Joe doesn't use node at all. Bob wants to use foo in node, so he wraps it in an npm module. Some time later, Joe starts using node, and wants to take over management of his program.
  2. Bob writes an npm module foo, and publishes it. Perhaps much later, Joe finds a bug in foo, and fixes it. He sends a pull request to Bob, but Bob doesn't have the time to deal with it, because he has a new job and a new baby and is focused on his new erlang project, and kind of not involved with node any more. Joe would like to publish a new foo, but can't, because the name is taken.
  3. Bob writes a 10-line flow-control library, and calls it foo, and publishes it to the npm registry. Being a simple little thing, it never really has to be updated. Joe works for Foo Inc, the makers of the critically acclaimed and widely-marketed foo JavaScript toolkit framework. They publish it to npm as foojs, but people are routinely confused when npm install foo is some different thing.
  4. Bob writes a parser for the widely-known foo file format, because he needs it for work. Then, he gets a new job, and never updates the prototype. Later on, Joe writes a much more complete foo parser, but can't publish, because Bob's foo is in the way.

The validity of Joe's claim in each situation can be debated. However, Joe's appropriate course of action in each case is the same.

  1. npm owner ls foo. This will tell Joe the email address of the owner (Bob).
  2. Joe emails Bob, explaining the situation as respectfully as possible, and what he would like to do with the module name. He adds the npm support staff support@npmjs.com to the CC list of the email. Mention in the email that Bob can run npm owner add joe foo to add Joe as an owner of the foo package.
  3. After a reasonable amount of time, if Bob has not responded, or if Bob and Joe can't come to any sort of resolution, email support support@npmjs.com and we'll sort it out. ("Reasonable" is usually at least 4 weeks, but extra time is allowed around common holidays.)

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.

If you see bad behavior like this, please report it right away.

Last modified January 08, 2016           Found a typo? Send a pull request!

Dispute Resolution

This document describes the steps that you should take to resolve module name disputes with other npm publishers.

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

The validity of Alice's claim in each situation can be debated. However, Alice's appropriate course of action in each case is the same.

  1. npm owner ls foo. This will tell Alice the email address of the owner (Yusuf).
  2. 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.
  3. 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.

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 February 02, 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>]

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 January 21, 2016           Found a typo? Send a pull request!

Copyright Policy

We take notices of potential copyright infringement seriously. If a user or other party has alleged that material on the npm website is infringing a copyright of such party or another third-party, the notice should be forwarded immediately to abuse@npmjs.com, who will work with legal counsel to resolve the dispute. If legal determines the notice satisfies all requirements under the United States Digital Millennium Copyright Act, then access to the allegedly infringing material must be promptly removed or disabled. We will then make a good faith effort to give notice of the claimed infringement to the user that posted the allegedly infringing material.

We respect the intellectual property of others and ask that you do too. If you believe any package or other materials available through the Service violates a copyright held by you and you would like to submit a notice pursuant to the Digital Millennium Copyright Act or other similar international law, you can submit a notice to our agent for service of notice at:

Abuse Team
npm, Inc.
1999 Harrison St, Ste 1150
Oakland CA 94612 USA
+1-510-858-7608
abuse@npmjs.com

Please make sure your notice meets the Digital Millennium Copyright Act requirements.

Please note that a copy of each legal notice we receive is also sent to Lumen Database for publication (with any user's personal information removed).

If the posting user objects to removal of the material, such user may file a counter notice. If we receive a counter notice from such user meeting the requirements of the DMCA, we will use good faith efforts to notify the complainant of such counter notice reinstate access to the material within 10-14 business days unless the complainant notifies us that it has filed a lawsuit against the allegedly infringing user. If we do not receive a counter notice from such user within 10 business days of giving notice of the claimed infringement, we reserve the right to permanently delete the material at issue.

We will terminate the accounts of users who are repeat infringers. Note, npm cannot provide legal advice to users (whether making a complaint or defending against a complaint), and we should ask users with legal questions to seek an attorney.

Last modified February 02, 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 January 08, 2016           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 January 08, 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 January 08, 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 January 21, 2016           Found a typo? Send a pull request!

If your organization uses GitHub or GitHub Enterprise, npm On-Site can be configured to automatically use them for login and access control. Simply add a repository field to your package.json that points to your repo:

{
  ..
  "repository": {
    "url": "git://github.mycompany.com/myco/mypackage.git"
  }
}

npm On-Site restricts installation of your package to users who have access to the repo for that package, and restricts publishing of that package to users who have commit access to the repo.

To point npm On-Site at your GitHub Enterprise appliance:

  1. visit the admin console at http://myreg.mycompany.com:8800
  2. choose GitHub as the authentication strategy.
  3. choose GitHub Enterprise.
  4. enter your GitHub Enterprise appliance's host and scheme.

If you use two-factor authentication for your GitHub account, you will need to manually generate a token and add it to your .npmrc file.

  1. Visit github.com/settings/tokens/new to create a new "Personal access token".
  2. Use a descriptive name for your token, like "myco npmE"
  3. Leave the default scopes as they are.
  4. Click "Generate Token" and you'll be redirected to a new page that displays your token. Copy the token right away, as it will only be displayed on screen once.
  5. Copy the token and paste it into the bottom of your .npmrc file:
@myco:registry=https://npme-private.npmjs.com/
//npme-private.npmjs.com/:_authToken=3aa689a8a6772ab997bb333d096b8c1f48a9ccc

Note: you do not need to run npm login if you set up two-factor authentication this way.

Last modified January 19, 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 January 08, 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 January 08, 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 January 08, 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] [--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).

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 elminate some deduping.

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.

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 29, 2016           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 January 08, 2016           Found a typo? Send a pull request!

npm On-Site Installation Guide

This document is meant to be a comprehensive guide to installing npm On-Site onto your server. When you are done going through the steps, you should have a usable private registry and website.

For details on configuration settings post-installation, please see this page.

Before you get started, please make sure you have the following ready to go:

The installation consists of these 4 main steps.

  1. Install Node.js and npm via instructions here
  2. Install npmo: sudo npm install npmo -g --unsafe
  3. Configure your instance via admin web console at:
    https:<your-server>:8800
  4. Start the services from the Dashboard there

Your npm On-Site instance will then be fully operational!

Follow along for details of each of the 4 main steps.

Node.js and npm are required to run the npmo installer in the next main step.

npm On-Site is distributed via the npmo package, which acts as an installer and CLI tool. It will automatically install Docker and an orchestration layer that comes with its own CLI (replicated) and runs an admin web console on port 8800 of your server. Once npmo is installed, you will need to complete the installation by configuring your instance using the admin web console.

Once the installer is complete, make sure that the docker and replicated daemons are running:

$ sudo ps aux | grep -e docker -e replicated
root      4354  1.5  1.1 495888 90560 ?        Ssl  16:40   6:57 /usr/bin/replicated -d
root      4363  0.0  0.1 115824 12924 ?        Ssl  16:40   0:11 /usr/bin/replicated-ui -d
root      4371  0.0  0.1 107200  7864 ?        Ssl  16:40   0:00 /usr/bin/replicated-updater -d
root      6512  1.2  0.6 1579584 50292 ?       Ssl  16:54   5:28 /usr/bin/docker daemon -H fd://

If any are not up, try running the installer again. On some systems, it's possible that dependencies may not be loaded in the correct order the first time.

Once you have confirmed the daemons are running, there will be an admin web console listening on port 8800. You can now use it to configure your On-Site instance and complete the installation.

At this point, the virtual environment and orchestration layer are in place, but the services that make up the registry are not yet installed and running. To complete this phase, you'll first need to set some things up in the admin web console and activate your instance with your license key.

With configuration settings saved, the admin console will direct you to the Dashboard where you can view the status of the registry services. If the top-left panel does not say "Starting", then hit the "Start Now" button.

If everything looks good, it's time to configure your npm CLI client and start publishing and installing private packages. Congrats!

Last modified January 19, 2016           Found a typo? Send a pull request!

npm On-Site

npm On-Site allows you to run npm's infrastructure behind your company's firewall. It's designed for teams that need:

npm On-Site is the same codebase that powers the public registry, it works with the same standard npm client you already use, but provides the features needed by larger organizations who are now enthusiastically adopting node. It's built by npm, Inc., the sponsor of the npm open source project and the host of the public npm registry.

Last modified November 29, 2015           Found a typo? Send a pull request!

Nice People Matter: npm is hiring

We currently are looking for interns to join us in summer 2015. Even if that's not what you're looking for, 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 November 29, 2015           Found a typo? Send a pull request!

Copyright (c) npm, Inc. and Contributors All rights reserved.

npm is released under the Artistic License 2.0, subject to additional terms that are listed below.

The text of the npm License follows and the text of the additional terms follows the Artistic License 2.0 terms:

The Artistic License 2.0

Copyright (c) 2000-2006, The Perl Foundation.

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Preamble

This license establishes the terms under which a given free software Package may be copied, modified, distributed, and/or redistributed. The intent is that the Copyright Holder maintains some artistic control over the development of that Package while still keeping the Package available as open source and free software.

You are always permitted to make arrangements wholly outside of this license directly with the Copyright Holder of a given Package. If the terms of this license do not permit the full use that you propose to make of the Package, you should contact the Copyright Holder and seek a different licensing arrangement.

Definitions

"Copyright Holder" means the individual(s) or organization(s)
named in the copyright notice for the entire Package.

"Contributor" means any party that has contributed code or other
material to the Package, in accordance with the Copyright Holder's
procedures.

"You" and "your" means any person who would like to copy,
distribute, or modify the Package.

"Package" means the collection of files distributed by the
Copyright Holder, and derivatives of that collection and/or of
those files. A given Package may consist of either the Standard
Version, or a Modified Version.

"Distribute" means providing a copy of the Package or making it
accessible to anyone else, or in the case of a company or
organization, to others outside of your company or organization.

"Distributor Fee" means any fee that you charge for Distributing
this Package or providing support for this Package to another
party.  It does not mean licensing fees.

"Standard Version" refers to the Package if it has not been
modified, or has been modified only in ways explicitly requested
by the Copyright Holder.

"Modified Version" means the Package, if it has been changed, and
such changes were not explicitly requested by the Copyright
Holder.

"Original License" means this Artistic License as Distributed with
the Standard Version of the Package, in its current version or as
it may be modified by The Perl Foundation in the future.

"Source" form means the source code, documentation source, and
configuration files for the Package.

"Compiled" form means the compiled bytecode, object code, binary,
or any other form resulting from mechanical transformation or
translation of the Source form.

Permission for Use and Modification Without Distribution

(1) You are permitted to use the Standard Version and create and use Modified Versions for any purpose without restriction, provided that you do not Distribute the Modified Version.

Permissions for Redistribution of the Standard Version

(2) You may Distribute verbatim copies of the Source form of the Standard Version of this Package in any medium without restriction, either gratis or for a Distributor Fee, provided that you duplicate all of the original copyright notices and associated disclaimers. At your discretion, such verbatim copies may or may not include a Compiled form of the Package.

(3) You may apply any bug fixes, portability changes, and other modifications made available from the Copyright Holder. The resulting Package will still be considered the Standard Version, and as such will be subject to the Original License.

Distribution of Modified Versions of the Package as Source

(4) You may Distribute your Modified Version as Source (either gratis or for a Distributor Fee, and with or without a Compiled form of the Modified Version) provided that you clearly document how it differs from the Standard Version, including, but not limited to, documenting any non-standard features, executables, or modules, and provided that you do at least ONE of the following:

(a)  make the Modified Version available to the Copyright Holder
of the Standard Version, under the Original License, so that the
Copyright Holder may include your modifications in the Standard
Version.

(b)  ensure that installation of your Modified Version does not
prevent the user installing or running the Standard Version. In
addition, the Modified Version must bear a name that is different
from the name of the Standard Version.

(c)  allow anyone who receives a copy of the Modified Version to
make the Source form of the Modified Version available to others
under

    (i)  the Original License or

    (ii)  a license that permits the licensee to freely copy,
    modify and redistribute the Modified Version using the same
    licensing terms that apply to the copy that the licensee
    received, and requires that the Source form of the Modified
    Version, and of any works derived from it, be made freely
    available in that license fees are prohibited but Distributor
    Fees are allowed.

Distribution of Compiled Forms of the Standard Version or Modified Versions without the Source

(5) You may Distribute Compiled forms of the Standard Version without the Source, provided that you include complete instructions on how to get the Source of the Standard Version. Such instructions must be valid at the time of your distribution. If these instructions, at any time while you are carrying out such distribution, become invalid, you must provide new instructions on demand or cease further distribution. If you provide valid instructions or cease distribution within thirty days after you become aware that the instructions are invalid, then you do not forfeit any of your rights under this license.

(6) You may Distribute a Modified Version in Compiled form without the Source, provided that you comply with Section 4 with respect to the Source of the Modified Version.

Aggregating or Linking the Package

(7) You may aggregate the Package (either the Standard Version or Modified Version) with other packages and Distribute the resulting aggregation provided that you do not charge a licensing fee for the Package. Distributor Fees are permitted, and licensing fees for other components in the aggregation are permitted. The terms of this license apply to the use and Distribution of the Standard or Modified Versions as included in the aggregation.

(8) You are permitted to link Modified and Standard Versions with other works, to embed the Package in a larger work of your own, or to build stand-alone binary or bytecode versions of applications that include the Package, and Distribute the result without restriction, provided the result does not expose a direct interface to the Package.

Items That are Not Considered Part of a Modified Version

(9) Works (including, but not limited to, modules and scripts) that merely extend or make use of the Package, do not, by themselves, cause the Package to be a Modified Version. In addition, such works are not considered parts of the Package itself, and are not subject to the terms of this license.

General Provisions

(10) Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

(11) If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

(12) This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

(13) This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

(14) Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The following additional terms shall apply to use of the npm software, the npm website, the npm repository and any other services or products offered by npm, Inc.:

"Node.js" trademark Joyent, Inc. npm is not officially part of the Node.js project, and is neither owned by nor affiliated with Joyent, Inc.

"npm" and "The npm Registry" are owned by npm, Inc. All rights reserved.

Modules published on the npm registry are not officially endorsed by npm, Inc. or the Node.js project.

Data published to the npm registry is not part of npm itself, and is the sole property of the publisher. While every effort is made to ensure accountability, there is absolutely no guarantee, warrantee, or assertion expressed or implied as to the quality, fitness for a specific purpose, or lack of malice in any given npm package. Packages downloaded through the npm registry are independently licensed and are not covered by this license.

Additional policies relating to, and restrictions on use of, npm products and services are available on the npm website. All such policies and restrictions, as updated from time to time, are hereby incorporated into this license agreement. By using npm, you acknowledge your agreement to all such policies and restrictions.

If you have a complaint about a package in the public npm registry, and cannot resolve it with the package owner, please email support@npmjs.com and explain the situation. See the npm Dispute Resolution policy for more details.

Any data published to The npm Registry (including user account information) may be removed or modified at the sole discretion of the npm server administrators.

"npm Logo" contributed by Mathias Pettersson and Brian Hammond, use is subject to https://www.npmjs.com/policies/trademark

"Gubblebum Blocky" font Copyright (c) by Tjarda Koster, https://jelloween.deviantart.com included for use in the npm website and documentation, used with permission.

This program uses several Node modules contained in the node_modules/ subdirectory, according to the terms of their respective licenses.

Last modified February 02, 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 globally-installed symbolic link from prefix/package-name to the current folder (see npm-config for the value of prefix).

Next, in some other location, npm link package-name will create a symlink from the local node_modules folder to the global symlink.

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

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 January 08, 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: 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.

Last modified January 08, 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.

prod / production

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 January 08, 2016           Found a typo? Send a pull request!

Mirroring the public registry

Sometimes you want your private registry to maintain copies of packages from the public registry. This is called mirroring, and companies do it for a number of reasons:

You can set up different policies to dictate how your npm On-Site server manages mirroring.

NOTE: If you want clients to use the mirrored packages from your npm On-Site server instead of accessing them from the public registry, the clients must be configured to do so.

The default policy for mirroring is the whitelist policy. A whitelist provides a list of packages which should be copied to npm On-Site and periodically updated from the public registry.

The default location for the whitelist is /usr/local/lib/npme/data/whitelist.

You can configure what packages should be copied from the public registry to npm On-Site on the server. Add packages to your whitelist by running this command on the server:

npmo add-package <packagename>

This will trigger mirroring for that package and all of its dependencies.

If you do not want to set up your whitelist manually in advance, you can also configure your server to copy packages to your npm On-Site server (and add them to the whitelist automatically) when they are requested by a client. For example, if a client requested lodash from your npm On-Site server and it did not exist, then npm On-Site would look for lodash in the public registry, copy it over, add it to the whitelist, and then serve it to the client.

To allow clients to add packages to the whitelist, visit npm On-Site's admin console and set Read through cache to Yes.

A full mirror will copy all packages from the public registry to your npm On-Site server. Enable this by setting policy to apply during replication to mirror in npm On-Site's admin console (http://myreg.mycompany.com:8800).

Last modified November 29, 2015           Found a typo? Send a pull request!

No authentication

If you do not need authentication or authorization at all (for example, you're only running npm On-Site inside your firewalled, private network), you can configure npm On-Site to accept whatever credentials users log in with, and allow everyone access to everything.

In order to do so, visit npm On-Site's admin console, and choose the Open authentication strategy.

The npm CLI will still require that you log in in order to publish packages, but you can just log in with any credentials (although the username you input will be inserted into the package document - for example in the maintainers field).

Last modified November 29, 2015           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++ is 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, check the issues list or ask on the mailing 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 January 08, 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"

NOTE: Because local (per-project or per-user) .npmrc files can contain sensitive credentials, they must be readable and writable only by your user account (i.e. must have a mode of 0600), otherwise they will be ignored by npm!

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 08, 2016           Found a typo? Send a pull request!

npm Open-Source Terms

These npm Open Source terms of use (these Terms) govern access to and use of https://www.npmjs.com (the Website) as well as the "npm Public Registry" at https://registry.npmjs.org (the Public Registry). Both the Website and the Public Registry are operated by npm, Inc. (npm). The Website and the Public Registry are referred to together as npm Open Source throughout these Terms.

These npm Open Source Terms were last updated on December 1, 2015. You can review prior versions at https://github.com/npm/policies/commits/master/open-source-terms.md.

These Terms include a number of important provisions that affect your rights and responsibilities, such as the disclaimers in "Disclaimers", limits on npm's liability to you in "Limits on Liability", and an agreement to arbitrate disputes individually in "Arbitration".

npm offers additional, paid services (Paid Services) that are subject to additional terms:

npm Open Source and any Paid Services you may agree to use are together called npm Services throughout these Terms.

You may only access or use npm Services by agreeing to these Terms. If npm adds any additional functionality to npm Services, you must agree to these Terms to use new features, too. You show your agreement with npm on these Terms by by creating a user account (your Account) or by accessing or using npm Services without creating an account. The agreement between you and npm is a legally binding contract (this Agreement).

npm may change these Terms and the additional terms for Paid Services in the future. npm will post changes on the Website with a new "last updated" date. If you have an Account, npm will notify you of changes by e-mail to the address provided for your Account, by a message on the Website, or both. If you do not have an account, npm may notify you of changes by a general announcement via the Website, but it is up to you to check for changes to these Terms. After receiving notice of changes to these Terms, you must accept those changes to continue using npm Services. You accept changes to these Terms by continuing to use npm Services. npm may change, suspend, or discontinue npm Services at any time without notice or liability to you.

npm respects your privacy and limits use and sharing of information about you collected by npm Services. The privacy policy at https://www.npmjs.com/policies/privacy (the Privacy Policy) describes these policies. npm will abide by the Privacy Policy and honor the privacy settings that you choose via npm Services.

npm respects the exclusive rights of copyright holders and responds to notifications about alleged infringement via npm Services per the copyright policy at https://www.npmjs.com/policies/dmca (the Copyright Policy).

npm resolves disputes about package names in the Public Registry per the policy at https://www.npmjs.com/policies/disputes (Dispute Policy).

Use of all npm Services is governed by the code of conduct at https://www.npmjs.com/policies/conduct (Code of Conduct).

npm permits use of npm trademarks per the policy at https://www.npmjs.com/policies/trademark.

Subject to these Terms, npm grants you permission to use npm Open Source. That permission is not exclusive to you, and you cannot transfer it to anyone else.

Your permission to use npm Open Source entitles you to do the following:

  1. You may search for, download, publish, and manage packages of computer code (Packages) in the Public Registry, and otherwise interact with the Public Registry, via the command-line tool published by npm at https://www.github.com/npm/npm (the CLI).

  2. You may search for, download, publish, and manage Packages using software other than CLI via application programming interfaces that npm publicly documents or makes available for public use (Public APIs).

  3. You may search for and manage Packages in the Public Registry, and otherwise interact with the Public Registry, via the Website.

  4. You may update and manage your Account via the Website.

Your permission to use npm Open Source, as well as any permission you may have to use Paid Services, are subject to the following conditions:

  1. You must be at least 13 years of age to use npm Services.

  2. You may not use npm Services after npm says you may not, such as by disabling your Account.

  3. You must use npm Services only in accordance with "Acceptable Use".

  1. You will abide by the Code of Conduct and the Dispute Policy.

  2. You will not submit any content that is illegal, offensive, or otherwise harmful. You will not submit any content in violation of law, infringing the intellectual property rights of others, violating the privacy or other rights of others, or in violation of any agreement with a third party.

  3. You will not disclose information that you do not have the right to disclose, such as confidential information of others.

  4. You will not copy or share any personally identifiable information of any other person without their specific permission.

  5. You will not violate any applicable law.

  6. You will not use or attempt to use another person's Account without their specific permission.

  7. You will not buy, sell, or otherwise trade in user names, organization names, names for Packages, or any other names reserved on npm Services, for money or other compensation.

  8. You will not send advertisements, chain letters, or other solicitations via npm Services.

  9. You will not automate access to, use, or monitor the Website, such as with a web crawler, browser plug-in or add-on, or other computer program that is not a web browser. You may replicate data from the Public Registry using the Public APIs per this Agreement.

  10. You will not use npm Services to send e-mail to distribution lists, newsgroups, or group mail aliases.

  11. You will not submit material containing malicious computer code, such as computer viruses, computer worms, rootkits, back doors, adware, or spyware, to npm Services in such a way that you should expect other users of npm Services to unwittingly execute that malicious code.

  12. You will not falsely imply that you are affiliated with or endorsed by npm.

  13. You will not operate illegal schemes, such as pyramid schemes, via npm Services.

  14. You will not deep-hyperlink to images or other non-hypertext content served by npm Services.

  15. You will not remove any marking indicating proprietary ownership from any material got via npm Services.

  16. You will not display any portion of the Website via an HTML IFRAME.

  17. You will not disable, avoid, or circumvent any security or access restrictions of npm Services, or access parts of npm Services not intended for access by you.

  18. You will not strain infrastructure of npm Services with an unreasonable volume of requests, or requests designed to impose an unreasonable load on IT systems underlying npm Services.

  19. You will not encourage or assist any other person in violation of "Acceptable Use".

npm may investigate and prosecute violations of this Agreement to the fullest legal extent. npm may notify and cooperate with law enforcement authorities in prosecuting violations of this Agreement.

You must create and log into an Account to access features of some npm Services, including npm Open Source.

To create an Account, you must provide certain information about yourself, as required by the account creation form on the Website or the CLI. If you create an Account, you will provide, at a minimum, a valid e-mail address. You will keep that e-mail address up-to-date. You will not impersonate any other individual. You may delete your Account at any time by sending an e-mail to support@npmjs.com.

You will be responsible for all action taken using your account, whether authorized by you or not, until you either close your account or give npm notice that the security of your Account has been compromised. You will notify npm immediately if you suspect the security of your Account has been compromised. You will select a secure password for your Account. You will keep your password secret.

npm may restrict, suspend, or terminate your Account according to the Copyright Policy, if npm reasonably believes that you are in breach of these Terms, or if npm reasonably believes that you have misused npm Services.

Your Content

Nothing in this Agreement gives npm any ownership rights in intellectual property that you share with npm Services, such as your Account information or any Packages you share with npm Services (Your Content). Nothing in this Agreement gives you any ownership rights in npm intellectual property provided via npm Services, like software, documentation, trademarks, service marks, logotypes, or other distinguishing graphics.

Between you and npm, you remain solely responsible for Your Content. You will not wrongly imply that Your Content is sponsored or approved by npm. npm will not be obligated to store, maintain, or provide copies of your content, except per the Privacy Policy.

npm may remove Your Content from npm Services without notice if npm suspects Your Content was submitted or used in violation of "Acceptable Use", as well as per the Copyright Policy.

You own Your Content, but grant npm a free-of-charge license to provide Your Content to users of npm Services. That license allows npm to make copies of and publish Your Content, as well as to analyze Your Content and share results with users of npm Services. npm may run computer code in Your Content to analyze it, but the license does not give npm any additional rights to run your code for its functionality in npm products or services. The license lasts, for each piece of Your Content, until the last copy disappears from npm's backups, caches, and other systems, after you delete it from the Website or the Public Registry.

Others who receive Your Content via npm Services may violate the terms on which you license Your Content. You agree that npm will not be liable to you for those violations or their consequences.

npm welcomes your feedback and suggestions for npm Services. You agree that npm will be free to act on feedback and suggestions you provide without further notice, consent, or payment. You will not submit feedback or suggestions that you consider confidential or proprietary.

You will indemnify npm, its officers, directors, employees, representatives, and agents, and hold them harmless for, all liability, expenses, damages, and costs from any third-party claims, demands, lawsuits, or other proceedings alleging that Your Content, your use of npm Services, or both, violate the intellectual property right of a third party, this Agreement, or applicable law. You will not settle any such proceeding without the prior written consent of npm. npm will notify you of any such proceeding it becomes aware of.

Use of npm Services is at your sole risk. npm Services are provided on an "as is" and "as available" basis. npm expressly disclaims all warranties of any kind, whether express, implied, or statutory, including implied warranties of title, noninfringement, merchantability, and fitness for a particular purpose.

npm makes no warranty that npm Services will meet your requirements, operate in an uninterrupted, timely, secure, or error-free manner, or that errors in npm Services will be corrected.

You receive material via npm Services at your sole risk. You will be solely responsible for any damage to your computer system and network, as well as any data loss that may result from use of npm Services or material received via npm Services.

npm Services may provide information and software that is inaccurate, incomplete, misleading, illegal, offensive, or otherwise harmful. npm may, but does not promise to, review content provided by npm Services.

npm Services provide information about ownership and licensing of Packages, as provided by those Packages' publishers. That information may be wrong. npm cannot and does not provide legal advice.

npm Services may hyperlink to and integrate with third-party applications, websites, and other services. You decide whether and how to use and interact with such services. npm does not make any warranty regarding such services or content they may provide, and will not be liable to you for any damages related to such services. Use of such third-party services may be governed by other terms and privacy notices that are not part of this Agreement and are not controlled by npm.

Neither npm nor any third-party service provider used by npm to provide npm Services will, under any circumstances, be liable to you for any indirect, incidental, consequential, special, or exemplary damages related to your use of npm Services or this Agreement, whether based on breach of contract, breach of warranty, tort (including negligence, product liability, or otherwise), or any other pecuniary loss, and whether or not npm has been advised of the possibility of such damages.

To the maximum extent permitted by law, npm's liability to you for any damages related to this Agreement, for any one or more causes and regardless of the form of action, will not exceed $50.

Some jurisdictions do not allow exclusion of certain warranties or limits on liability for incidental or consequential damages. Some of "Disclaimers" and "Limits on Liability" may not apply to you.

Either you or npm may terminate this Agreement at any time with notice to the other.

On termination of this Agreement, your permission to use npm Open Source, as well any permission you may have to access Paid Services under additional terms, also terminate.

The following provisions survive termination of this Agreement: "Your Content", "Feedback", "Indemnity", "Disclaimers", "Limits on Liability", and "General Terms". Users of npm Services may continue to copy and share Your Content after termination of this Agreement.

There is no charge for use of npm Open Source. If you use Paid Services, these payment terms apply.

When enabling Paid Services, you must provide all the payment card details requested by the Website (your Payment Details). Those details must be for a valid payment card that you have the right to use (your Payment Card). You must keep your Payment Details up-to-date via the Website.

You can disable Paid Services at any time via the Website. npm will not refund any payment you have already made for Paid Services when you disable Paid Services.

Dollar amounts throughout this Agreement are amounts of United States Dollars. You must pay for Paid Services in United States Dollars.

Dollar amounts throughout this Agreement do not include tax. You will pay any tax.

If a provision of this Agreement is unenforceable as written, but could be changed to make it enforceable, that provision should be modified to the minimum extent necessary to make it enforceable. Otherwise, that provision should be removed.

You may not assign this Agreement. npm may assign this Agreement to any affiliate of npm, any third party that obtains control of npm, or any third party that purchases assets of npm relating to npm Services. Any purported assignment of rights in breach of this provision is void.

Neither the exercise of any right under this Agreement, nor waiver of any breach of this Agreement, waives any other breach of this Agreement.

This Agreement, together with the additional terms for Paid Services and npm software that you and npm agree to, embody all the terms of agreement between you and npm about npm Services. This Agreement supersedes any other agreements about npm Services, written or not.

The law of the State of California will govern any dispute, including any legal proceedings, relating to this Agreement or your use of npm Services (a Dispute).

You and npm will seek injunctions related to this agreement only in state or federal court in San Francisco, California. Neither you nor npm will object to jurisdiction, forum, or venue in those courts.

Other than to seek an injunction, you and npm will resolve any Dispute by binding American Arbitration Association arbitration. Arbitration will follow the AAA's Commercial Arbitration Rules and Supplementary Procedures for Consumer Related Disputes. Arbitration will happen in San Francisco, California. You will settle any Dispute as an individual, and not as part of a class action or other representative proceeding, whether as the plaintiff or a class member. No arbitrator will consolidate any Dispute with any another arbitration without npm's permission.

Any arbitration award will include costs of the arbitration, reasonable attorneys' fees, and reasonable costs for witnesses. You or npm can enter arbitration awards in any court with jurisdiction.

You may send notice to npm and questions about the terms governing npm products and services by mail to npm, Inc., Legal Department, 1999 Harrison Street, Suite 1150, Oakland, California 94612, or by e-mail to legal@npmjs.com. npm may send you notice using the e-mail address you provide for your Account or by posting a message to the homepage or your Account page on the Website.

Last modified February 02, 2016           Found a typo? Send a pull request!

npm Organization Payment Plan

This npm Organization Payment Plan (this Payment Plan) supplements the terms for npm Open Source offered by npm, Inc. (npm) at https://www.npmjs.com/policies/open-source-terms (npm Open Source Terms), as well as the terms for npm Private Packages (npm Private Packages) at https://www.npmjs.com/policies/private-terms (npm Private Packages Terms). This Payment Plan governs payment for npm Private Packages organizations (Organizations) and use of npm Private Packages by user accounts added as members of those Organizations.

This Payment Plan was last updated on December 1, 2015. You can review prior versions at https://github.com/npm/policies/commits/master/personal-plan.md.

Under this Payment Plan, you may create one or more Organizations.

You will pay a minimum of $14.00 via your Payment Card when you create an Organization and at the end of each month-long period, until you delete the organization. This minimum payment entitles you to add up to two user accounts not otherwise entitled to use npm Private Packages as member of the organization (New Private Packages Accounts), and an unlimited number of other user accounts. You will pay $7.00 via your Payment Card per each additional New Private Package User (above two) that you add to an Organization, when you add them as a member and at the end of each month-long period.

The account holders of New Private Packages Accounts that you add as members of your Organizations will be entitled to use npm Private Packages under this Payment Plan, provided the account holders agree to and abide by the npm Open Source Terms and npm Private Packages Terms. These rights will not limit npm's right to enforce the npm Open Source Terms, npm Private Packages Terms, or other terms.

Last modified February 02, 2016           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-access for more details
  2. npm access see npm-team 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 January 08, 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 January 21, 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>

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 January 08, 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 January 08, 2016           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.

NOTE: This is not the same as "url". If you put a "url" field, then the registry will think it's a redirection to your package that has been published somewhere else, and spit at you.

Literally. Spit. I'm so not kidding.

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" : "http://opensource.org/licenses/ISC"
  }
}

// Not valid metadata
{ "licenses" :
  [
    { "type": "MIT"
    , "url": "http://www.opensource.org/licenses/mit-license.php"
    }
  , { "type": "Apache-2.0"
    , "url": "http://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:

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

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.

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": "visionmedia/express",
    "mocha": "visionmedia/mocha#4727d357ea"
  }
}

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 prepublish 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": {
    "prepublish": "coffee -o lib/ -c src/waza.coffee"
  },
  "main": "lib/waza.js"
}

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

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

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

Note that, unless the user has set the engine-strict config flag, this field is advisory only.

This feature was deprecated with 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.

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 29, 2016           Found a typo? Send a pull request!

npm Personal Payment Plan

This npm Personal Payment Plan (this Payment Plan) supplements the terms for npm Open Source offered by npm, Inc. (npm) at https://www.npmjs.com/policies/open-source-terms (npm Open Source Terms), as well as the terms for npm Private Packages (npm Private Packages) at https://www.npmjs.com/policies/private-terms. This Payment Plan governs payment for use of npm Private Packages by a single user account.

This Payment Plan was last updated on December 1, 2015. You can review prior versions at https://github.com/npm/policies/commits/master/personal-plan.md.

You will pay $7.00 via your Payment Card when you enable npm Private Packages for your Account by selecting this Payment Plan, and at the beginning of each successive month-long period while this Payment Plan remains selected for your Account.

Last modified February 02, 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 January 08, 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 January 08, 2016           Found a typo? Send a pull request!

npm Privacy Policy

We track data about users of the npm website, the npm public registry and any other services we may offer from time to time.

This page tells you what we track, and what we do with it.

All requests to the registry are logged and retained by npm, Inc. These requests include non-personally identifiable information such as the package requested and the time of the request, as well as potentially personally identifiable information such as the IP address of the requestor.

For example, this is a sample of the kind of data we track in our logs when you download a package:

2014-05-05T23:17:52Z 50.1.57.179 "-" "GET /npm-test-blerg" 200 "npm/1.4.10 node/v0.10.26 darwin x64" "install npm-test-blerg" "1db337334dbd3fc1" "MISS" "shield__cache_v41_ASH__ashburn_va_us" "cache-v41-ASH"
2014-05-05T23:17:53Z 50.1.57.179 "-" "GET /npm/public/registry/npm-test-blerg/_attachments/npm-test-blerg-0.1000.1.tgz" 200 "npm/1.4.10 node/v0.10.26 darwin x64" "install npm-test-blerg" "1db337334dbd3fc1" "MISS" "shield__cache_c99_CHI__chi_il_us" "cache-c99-CHI"

This includes a number of things:

  1. The date and time.
  2. The IP address of the requestor.
  3. The HTTP request URL and method.
  4. The HTTP response status code.
  5. The user-agent string, which includes the versions of Node and npm in use.
  6. Data about the CDN cache.
  7. A random npm-session header, unique to a single invocation of the npm command line utility.
  8. A referer header, which will indicate the command that was invoked.

For example, if you type npm install express, then all HTTP requests as a result of that command will indicate that they are related to a single action, and that the originating request was for the express module.

Note that different versions of npm may send different information, so some of the fields may not be tracked for all requests.

Like most website operators, npm, Inc. collects non-personally-identifying information of the sort that web browsers and servers typically make available, such as the browser type, language preference, referring site, and the date and time of each visitor request. npm, Inc.’s purpose in collecting non-personally identifying information is to better understand how npm’s visitors use its website. From time to time, npm, Inc. may release non-personally-identifying information in the aggregate, e.g., by publishing a report on trends in website usage.

npm, Inc. also collects potentially personally-identifying information like Internet Protocol (IP) addresses. npm, Inc. does not use such information to identify its visitors, however, and does not disclose such information, other than under the same circumstances that it uses and discloses personally-identifying information, as described below.

The npm website uses Google Analytics to monitor and analyze user behavior. This service provides npm, Inc. with information on users' demographics, age, location, and interest categories, when such information is available. This information is not used to identify individual users, but can in some cases be very specific. You can learn more about the information gathered and retained by this service at the Google Analytics privacy policy. You can opt out of Google Analytics entirely with the Google Analytics opt-out browser addon.

The npm website uses Oracle Marketing Cloud to collect and manage leads for marketing purposes. Information on what data Oracle Marketing Cloud stores about users, how it is collected, and how it is used are available in Oracle Marketing Cloud & Oracle Data Cloud Privacy Policy.

The npm website uses Optimizely to test the effects of changes to the npm website on users' browsing experiences. Information on what data Optimizely stores about users, how it is collected, and how it is used are available in Optimizely' privacy policy.

In order to write information into the npm registry database (for example, to publish packages, bookmark packages, edit metadata, etc.) users may decide to provide certain personally identifying information including but not limited to: email address, username, password, personal website, and account names on other services such as GitHub, Twitter, and IRC.

When packages are published in the npm registry, the user responsible for the publish action is saved, along with the date and time of the publish. This information is shared on the website.

If you create an account or publish a package, your email address will be publicly disclosed.

If users do not want their information tracked in this manner, they can opt to not create an account. However, this means that some features of npm and the npm website will be unavailable to them.

We may use personally identifying information we have collected about you, including your email address, to provide you with news, notes, and recommendations. You can opt out of receiving such messages at any time by using the "unsubscribe" links or directions at the ends of messages you receive. In addition, we use collected personally identifying information to operate our business and the npm service. We do not disclose your personal information to unaffiliated third parties who may want to offer you their own products and services unless you have requested or authorized us to do so.

We may share your personal information with third parties or affiliates where it is necessary for us to complete a transaction or do something you have asked us to do. Likewise, we may share your personal information with third parties or affiliates with whom we have contracted to perform services on our behalf. Companies that act on our behalf are required to keep the personal information we provide to them confidential and to use the personal information we share only to provide the services we ask them to perform.

In addition, we may disclose personal information in the good faith belief that we are lawfully authorized to do so, or that doing so is reasonably necessary to comply with legal process or authorities, respond to any claims, or to protect the rights, property, or personal safety of npm, our users, our employees, or the public. In addition, information about our users, including personal information, may be disclosed or transferred as part of, or during negotiations of, any merger, sale of company assets, or acquisition.

A cookie is a string of information that a website stores on a visitor’s computer, and that the visitor’s browser provides to the website each time the visitor returns.

The npm website uses cookies to help identify and track visitors, their usage of the npm website, and their website access credentials. npm website visitors who do not wish to have cookies placed on their computers should set their browsers to refuse cookies before using npm, Inc.’s websites, with the drawback that certain features of npm, Inc.’s websites may not function properly without the aid of cookies.

Most packages published to the npm registry are open source, and freely available to all users of the npm service. We show basic package metadata on the npm website, in a variety of forms, so as to assist users in finding a package that meets their needs.

We may also inspect the contents of published packages to investigate any claims of malicious contents, or to debug problems that may occur in the process of running the service. For open source packages, we may also analyze the contents of published packages in an automated fashion to gain information about how people use npm packages. This information may be disclosed to third parties on our website, or in other forms. (Note that it is already freely available to anyone who downloads the packages themselves.)

If a package is published to the npm registry in such a way as to restrict read-access to the package, then we may still need to inspect the package contents on rare occasions. However, we never disclose information about a private package--including the fact that the package exists--to third parties who are not granted access to the package by the package's owners.

All user information is retained in raw form for such time as deemed appropriate by npm, Inc. It is shared with employees and contractors of npm, Inc., as needed to process information on npm, Inc.'s behalf.

Raw log data is not shared with third parties, but may be shared in aggregate. For example, every page on the npm includes a report on the number of downloads that module has received, and occasionally npm, Inc. may publish blog posts or reports on registry or website usage.

We also analyze log data for a variety of reasons, including counting up downloads and unique visitors, debugging production problems, tracking which versions of Node.js and npm are in use in the wild, and researching how npm packages are used together with one another. This helps us to better understand the usage patterns of npm, and make better decisions about the npm product.

The npm service is not intended for use by minor children (under the age of 18). Parents and guardians should monitor the use of the npm service by minor children. Children under age 13 should not use the npm service at all. If a child under age 13 submits personal information through any part of the service, and we become aware that the person submitting the information is under age 13, we will attempt to delete the information as soon as reasonably possible.

The npm service may contain links to other websites. Any personal information you provide on the linked pages is provided directly to that third party and is subject to that third party’s privacy policy. Except as described above, we are not responsible for the content or privacy and security practices and policies of websites to which we link. Links from the npm service to third parties or to other sites are provided for your convenience. We encourage you to learn about their privacy and security practices and policies before providing them with personal information.

The npm service is hosted in the United States. This Privacy Policy is intended to comply with privacy laws in the United States and may not comply with all privacy laws in other countries.

If you are a non-US user of the service, by using our service and providing us with data, you acknowledge, agree and provide your consent that your personal information may be processed in the United States for the purposes identified in this Privacy Policy. In addition, such data may be stored on servers located outside your resident jurisdiction, which may have less stringent privacy practices than your own. By using the npm service and providing us with your data, you consent to the transfer of such data and any less stringent privacy practices.

If you have any questions or concerns about how we track user information, or how that information is used, please contact us at once.

You may contact npm, Inc. via our contact form, by emailing legal@npmjs.com, or via snail mail at:

npm, Inc.
1999 Harrison Street
Suite 1150
Oakland CA 94612
USA

Although most changes are likely to be minor, npm, Inc. may change its Privacy Policy from time to time, and in npm, Inc.’s sole discretion. Any such changes will be posted on the npm blog, and the detailed history of changes can be found in the git repository history for this document.

npm, Inc. encourages visitors to frequently check this page for any changes to its Privacy Policy. Your continued use of the npm website and the npm public registry after any change in this Privacy Policy will constitute your acceptance of such change.

Parts of this policy document were originally included in the WordPress.org privacy policy, used with permission.

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

Last modified February 02, 2016           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 December 29, 2015           Found a typo? Send a pull request!

npm Private Packages Terms

These npm Private Packages Terms of Use (these npm Private Packages Terms) supplement the terms for npm Open Source offered by npm, Inc. (npm) at https://www.npmjs.com/policies/open-source-terms (npm Open Source Terms). They govern access to and use of npm Private Packages, the private package storage, delivery, organization management, and access control features of https://www.npmjs.com (the Website) and the npm public registry at https://registry.npmjs.org (the Public Registry).

These npm Private Packages Terms were last updated on December 1, 2015. You can review prior versions at https://github.com/npm/policies/commits/master/private-terms.md.

You may only access or use npm Private Packages by agreeing to the npm Open Source Terms as supplemented by these npm Private Packages Terms. If npm adds any additional functionality to npm Private Packages, you must agree to these npm Private Packages Terms to use those new features, too. You add these npm Private Packages Terms to your agreement with npm by using npm Private Packages with your account (your Account). These npm Private Packages Terms then become a part of the contract between you and npm, until you or npm disable npm Private Packages for your Account.

npm will provide the private package storage and delivery features and services described in the public documentation for npm Private Packages at https://www.npmjs.com/private-modules (the npm Private Packages Documentation). npm grants you permission to use those features and services.

npm will also provide the organization management and access control features described in the npm Private Packages Documentation, and grants you permission to use those features and services, for npm Private Packages "organizations" to which your Account belongs.

Permission to use npm Private Packages is not exclusive to you, and you may not transfer it to others. These npm Private Packages Terms do not give you permission to give others rights to use npm Private Packages. If you agree to a Payment Plan that gives you that right, you may do so only according to that Payment Plan.

Both your permission to use npm Private Packages and npm's commitment to provide npm Private Packages are subject to these npm Private Packages Terms, the npm Open Source Terms, and payment for use of npm Private Packages by your Account under a Payment Plan. Payment plans include:

  1. the npm Personal Payment Plan at https://www.npmjs.com/policies/personal-plan

  2. or the npm Organization Payment Plan at https://www.npmjs.com/policies/organization-plan

You may not use npm Private Packages unless you or someone else has agreed to a Payment Plan, enabled npm Private Packages for your Account under that Payment Plan, and made payment.

Last modified February 02, 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 January 08, 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.

Last modified January 21, 2016           Found a typo? Send a pull request!

npm On-Site Quickstart

This is the fastest way to get started with npm On-Site - your own private npm registry and website!

Here's what we're going to cover in this guide:

  1. Install npm On-Site on your server
  2. Configure and start your On-Site instance
  3. Configure the npm CLI to talk to your registry
  4. Publish, install, and search for packages

Minimal details are given for each step. For more exhaustive details, please see the linked docs pages.

Here's a quick video to help walk you through this process:

Last modified January 19, 2016           Found a typo? Send a pull request!

policies

These are the legal policies of npm, Inc.

These are updated from time to time. Their sources are stored in a git repository at https://github.com/npm/policies.

Last modified February 02, 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 January 08, 2016           Found a typo? Send a pull request!

Receiving Reports

This is a guide for npm staff for handling user reports of harassment, package name disputes, and other user-generated pain points.

It is shared publicly in order to add transparency in our process

Nothing in this document should be considered a hard and fast rule in cases where it runs contrary to npm's mission of creating a safe, inclusive, and productive platform for easily sharing JavaScript modules.

When in doubt, seek help from your fellow admin staff.

If someone would like to take over a module name from another user, and asks for help with this, please refer them to the "Dispute Resolution" documentation. In cases like this, the two parties tend to be relatively rational and professional, and it is best if we encourage things to continue in that direction.

The policy in brief, where "Alice" is the original author, and "Yusuf" is the person with the dispute:

  1. Yusuf emails Alice, explaining the reasons for wanting the module name, and CC's npm support.

  2. We set a timer for 4 weeks. If that lands on a holiday or something, err on the side of making the delay longer.

  3. At this point, one of three things have happened:

    a. Alice and Yusuf have resolved the situation in a way that works for both of them.

    b. Alice and Yusuf have reached an impasse, and cannot resolve the dispute.

    c. Alice has not responded to Yusuf at all.

By far, (a) is the most common occurrence, and the answer is simple: we do nothing. This is ideal.

When package name disputes can be handled amicably between users without any administrative involvement, everyone feels better about it. Everything we do in these cases should guide towards that endgame when possible.

If Alice has not responded, then we must make a judgment call. There are a few possible considerations:

  1. It could be that Alice has moved on to some other platform, doesn't care, and doesn't check this email address anymore, passed away, joined a monastery, meant to respond and forgot, who knows.
  2. Alice has decided that she's never going to hand the module name over, so there's no point even discussing it.

Abrupt dismissive autocratic administration has a way of upsetting people and bringing them out of hiding. We cannot safely assume that absence is evidence of apathy.

  1. Check the source control repository to see if Alice is writing patches, closing issues, etc.
  2. Check to see if Alice has published new versions of the module.
  3. Check to see if the module still works with the current version of Node, has a lot of dependents, etc.

If the module does appear abandoned, or if Yusuf's claim on the module is valid and that the hand-off would be less of a disruption than leaving an abandoned module in npm, then do this:

  1. Reply-all to the thread with something like the following message, customized for your own "voice" as necessary:

     Alice,

 I hope that you are well, and that you only missed this
 message because your life is too full of wonderful
 distractions to be bothered dealing with this issue.

 Yusuf is eager to take over the `fooblx` module on npm, and
 plans to actively develop it.

 Currently, it is [not actively developed, marked as
 deprecated, apparently abandoned, not compatible with the
 latest Node versions, whatever], so I'd like to hand it off to
 Yusuf to take over.

 If this causes you any stress or inconvenience, please let me
 know as soon as possible.

  2. Set a timer for 1 week.

  3. If Alice responds with concerns, then use diplomacy. Usually this comes down to telling Yusuf, "Sorry, you'll have to choose another name." Mostly, people are pretty receptive to this.

  4. If Alice still does not reply, then reply-all to the thread with something like this:

     Alice,

 As per the email last week regarding the fooblx module, we've
 decided to hand control over to Yusuf, who will be actively
 developing it.

 Yusuf,

 You are now a package maintainer on the fooblx module.

 Please leave the existing versions in place, and bump the
 major version, so that any prior users are minimally impacted.

 Thank you both for your patience and understanding.

 --i

Caveats and things to be sensitive of:

Note that this does not mean that we will always try to accommodate users' wishes. If a module name is offensive, the package contents are violating licenses or other intellectual property rules that could get us in trouble, or the package is empty (i.e., squatting), or otherwise violates the terms of use, we reserve the right to remove packages without any discussion.

Even in those cases, it is often best to try to give users a week or so to do things on their own, so that they can maintain a sense of ownership. Outright and obvious trolling or harassment is never tolerated, however.

These are cases where a user is reporting to us that someone is using the npm system for nefarious ends, or harassing other users in some other way.

In this case, we draw a very hard line, as communicated by our zero-tolerance anti-harassment policy.

Reports of abuse of npm are somewhat different than reports of abuse of npm users.

If a user is publishing a flood of empty squatting packages, spamming, phishing, offensive content, or other childish trolling aimed at the service rather than at a specific user, then the course of action is simple:

  1. Ban the user.
  2. Clean up the mess.

If it's possible that they are unaware that their behavior is not allowed, it is a good idea to not ban the user outright, but send them an email asking them to please stop the bad behavior.

Here's an example:

Subject: Empty/duplicate packages removed
From: Isaac Schlueter <isaacs@npmjs.com>
To: Some User <some-user@gmail.com>
Cc: npm support <support@npmjs.com>

Several empty and duplicated packages belonging to you were
removed.

Please do not publish empty packages to npm.  This causes
difficulty for others who may want to use names for new projects.

We do not allow "reserving" names for future use.  You must have
something to publish before taking a package name.  Otherwise, we
quickly end up with a lot of empty packages, and names being used
for no purpose.

If you continue to publish empty packages to npm, your username
and/or IP address may be blocked from accessing the service.

Thank you.

--i

Do not mention, involve, or CC the person who reported the bad behavior, as this can only result in added conflict. Briefly thank them for the report, and let them know that it's been dealt with.

This includes both abuse of npm users via the npm service, as well as auxiliary channels such as IRC, Twitter, GitHub, etc.

If it impacts npm users and degrades their experience of using the service, then it's our problem, and we take it seriously.

The vast majority of reports of harassment will come via written media (email, IRC, etc.) If you receive a report of harassment in a non-text format, ask the user for a written account if this is reasonable. If it is not, then take your own notes, or record it in a written format as soon as possible.

A verbal report lasting more than a minute or so is probably better conducted in a quiet/private place rather than in a public space, for the safety and comfort of the reporter. This also decreases the chances for someone to overhear sensitive information that the reporter may not want spread around at an event.

If the user would prefer to remain anonymous, please strip their name from the record prior to sharing it with the rest of the abuse team.

Try to get as much detail as you can about the incident. This will assist us later if we ever need to make a case to defend our choices, as well as inform future decisions about how these incidents could be avoided.

If the following information is not volunteered in the written or verbal report, ask for it/include it, but do not pressure them.

Generally we are not equipped for evidence gathering: do not going around "interviewing" others involved.

If someone reports that a user of the service or an attendee at an event has committed or is threatening violence towards another person, or other safety issues:

If everyone is presently physically safe, involve law enforcement or security only at a victim's request.

In many cases, reporting harassment to law enforcement is very unpleasant and may result in further harassment. Forcing victims to go to law enforcement will reduce reports of harassment (but not actual harassment). For more information, see Why Didn't You Report It?

A staff member can provide the list of emergency contacts and say something like "if you want any help reporting this incident, please let us know" and leave it at that.

These include things like harassing content in package names, conference talks, or harassment that took place in a crowded space.

Simply say "Thanks, this sounds like a breach of our anti-harassment policy. I am going to convene a meeting of a small group of people and figure out what our response will be."

Often, the best approach is similar to handling package name disputes. For example, a user may be a non-native English speaker, and not realize that a given term is offensive. It is our responsibility as the caretakers of npm to attempt to resolve this as amicably as possible.

Other times, this may be a matter of simply deleting some offensive packages and telling the user not to do it again.

In the most egregious cases, it may require banning the user account and/or IP address of an abusive troll.

Offer the reporter/victim a chance to decide if any further action is taken: "OK, this sounds like a breach of our anti-harassment policy. If you're OK with it I am going to convene a meeting of a small group of people and figure out what our response will be."

Pause, and see if they say they do not want this. Otherwise, go ahead.

Do not:

We should aim to take action as soon as reasonably possible. During the event, a response within the next half-day is usually an appropriate timeframe. After the event you may need more time to gather sufficient decision makers, but ideally responding within the same week or sooner is good.

Available staff should meet as soon as possible after a report to discuss:

Neither the complainant nor the alleged harasser should attend. (If the event was very widely witnessed, such as a harassing talk, this may be an exception to this guideline.) People with a conflict of interest should exclude themselves or if necessary be excluded by others.

As soon as possible, either before or during the above meeting, let the alleged harasser know that there is a complaint about them, let them tell someone their side of the story and that person takes it into the meeting.

As soon as possible after that meeting, let the harasser know what action is being taken. Give them a place to appeal to if there is one, but in the meantime the action stands. "If you'd like to discuss this further, please contact XYZ, but in the meantime, you must <something something>"

Do not ask for an apology to the victim. We have no responsibility to enforce friendship, reconciliation, or anything beyond lack of harassment between any two given users, and in fact doing so can contribute to someone's lack of safety while using our service.

Forcing a victim of harassment to acknowledge an apology from their harasser forces further contact with their harasser. It also creates a social expectation that they will accept the apology, forgive their harasser, and return their social connection to its previous status. A person who has been harassed will often prefer to ignore or avoid their harasser entirely. Bringing them together with a third party mediator and other attempts to "repair" the situation which require further interaction between them should likewise be avoided.

If the harasser offers to apologize to the victim (especially in person), strongly discourage it. In fact, discourage any further interaction with the offended party.

If a staff member relays an apology to the victim, it should be brief and not require a response. ("X apologizes and agrees to have no further contact with you" is brief. "X is very sorry that their attempts to woo you were not received in the manner that was intended and will try to do better next time, they're really really sorry and hope that you can find it in your heart to forgive them" is emphatically not.)

If the harasser attempts to press an apology on someone who would clearly prefer to avoid them, or attempts to recruit others to relay messages on their behalf, this may constitute continued harassment.

All (potentially de-identified) information about harassment reports should be stored for a period of at least 5 years, in an electronic format, accessible only by the npm abuse team.

Lifetime bans are handled by banning a username or IP address. If it ever becomes necessary, we will maintain a lifetime ban of users for in-person events as well.

In general, we handle disputes and harassment quietly. Our code of conduct explicitly forbids harassment, and we maintain our reputability on this point by enforcing that policy appropriately.

However, occasionally these events will spill out into public. In those cases, please let the npm executive team decide how best to communicate with the public.

When necessary, this will be communicated via the npm blog.

When it's necessary to communicate enforcement of our policy at an in-person event, a brief public statement to the attendees such as this would suffice:

"[thing] happened. This was a violation of our policy. We apologize for this. We have taken [action]. This is a good time for all attendees to review our policy at [location]. If anyone would like to discuss this further they can [contact us somehow]."

And then move on with the program.

People may be upset and wish to express their concerns to npm staff. We should be in "making the person feel heard" mode; it's important not to cross into "education mode". Hear them out, take notes as appropriate, thank them for their thoughts.

We should not share additional details of the incident with uninvolved parties.

If a user is upset and a staff member agrees that a wrong was done to them, it helps a lot to just say simply "I'm so sorry." (Rather than "but we tried really hard" or "no one told us" or etc., even if that was true. "I'm so sorry" goes a long way to defusing many people's anger.)

Whether or not a staffer agrees that a wrong was done to them, the user should be armed with an authority they can appeal to if talking wasn't enough. "Please email abuse@npmjs.com."

After we have had a chance to observe how the anti-harassment and dispute resolution policies work in the real situations, we may wish to change the policy to better address them.

Did anything unforeseen happen that there should be a rule about? Sometimes an unacceptable behavior does not warrant a whole new rule, but should be listed as a specific example of unacceptable behavior under an existing rule.

For the sake of consistency, if there are changes to a rule, we try to apply that rule moving forward, rather than retroactively. If a judgment call is made, record the decision and the justification, and perhaps codify it in a rule going forward so that users can more easily succeed in our community.

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.

Parts of this policy borrow heavily from the Geek Feminism Wikia guide.

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

Last modified February 02, 2016           Found a typo? Send a pull request!

npm, Inc.'s Recruiting Process

This document was once an internal document at npm, Inc. Because it is relevant to many people in our community, and we like transparency, we have decided to open it up to the world.

There is no expectation or requirement that you hire people in this way if you are not working at npm, Inc. This is just how we do it. If you apply for a job here, this may provide some clue as to what to expect.

From here on out, "you" refers to the npm, Inc. employee who is evaluating candidates for hire.

npm has a great brand for recruitment. Our applicants generally mention three things they particularly like:

None of these things have anything to do with node.js or JavaScript, and that's a great sign. Your conversations with applicants should communicate the value we place on these things.

Some simple guidelines:

We have an open source repo of former job descriptions to help you.

Role is identified.

Hiring Manager writes job description.

As resumes come into jobs@npmjs.com, HR will upload to and update Lever. It is the responsibility ofthe hiring manager to review resumes on a timely basis and if there are obvious "NO's" to let HR know immediately so the candidates can move forward with their job search.

Everyone who speaks to a candidate must put their notes in Lever. The #recruitment channel on slack is for discussing hiring pipeline status and recruitment plans, not individual candidates. (i.e. it's okay to ask "is Jane coming for an interview?" but not "I didn't like Jane because...").

  1. Post the job description.
  2. Wait at least 2 weeks after posting a job description before screening (don't screen as you go; screen as a batch).
  3. All incoming applicants MUST be put into Lever. If you receive one in your personal email account, please put into Lever and let HR know. This ensures that every application gets a personal response indicating we received it and a rough timeline for screening (e.g. "about 1 week from now").
  4. Hiring manager will read all available resumes and select 25-50% of those candidates for first-round screening. Anybody not selected is notified at this stage by HR.
  5. First-round screening is an informal, 20-30 minute discussion, by phone, Skype, or Google Hangout by the hiring manager, who will select roughly 50% of these candidates for second-round screens. Anybody not selected is notified at this stage by HR.
  6. Second-round screening is 2 longer conversations, 45-60 minutes, by phone or google hangout if the applicant is remote, or in-person if they are local. Hiring Manager will determine which prospective team-mates, or existing employees with relevant skillsets will be taking part in second-round conversations. For remote applicants always supply the phone number or google hangout name applicant-interviewer in the calendar invitation. Anybody not selected for this stage will be notified by HR.
  7. After the second round interviews, hiring manager meets with interviewers to select 1-3 candidates for a full team interview. Often by this point there will be one obviously best candidate, and it is fine to bring them in by themselves. Candidates not selected for the final round are notified at this stage by HR.
  8. Full team interview: the candidate comes in for lunch at noon (any day except Monday). The hiring manager will invite 6 staff members that the candidate is likely to be in contact with during their day. After lunch, anyone who hasn't yet spoken with the candidate, and the hiring manager deems necessary may request a 30-45 minute slot. For remote candidates after their flight, hotel etc. have been arranged HR will send them their itinerary and cc hiring manager, with a short "this might come in handy" note containing at least one contact number for emergencies and local cab or other transit options.
  9. After the full team interview, hiring manager and their team will take everyone's notes into account and make a final decision. After selecting the best candidate, we do not yet notify the other candidates.
  10. Reference checks: The candidate supplies 3 names and contact information of people they haveworked directly with; hiring manager has a discussion with at least 2. This is a final red-flag check and also gives the hiring manager a head-start on how to work best with the hire. Questions can include What dates did the candidate work there? What is the documented departure reason? Would you rehire?
  11. Hiring manager will consult with the selected candidate on salary, benefits, relocation, visa (at the moment npm lacks the legal resources to sponsor visas other than TN-1 visas for Canadian and Mexican citizens), and any other issues to make sure there are no unexpected barriers to a hire and a reasonable start date, and make a salary recommendation to the CEO.
  12. CEO will have a final conversation with the candidate, make salary offer (we will always offer the best salary we can afford, so there is not much room for negotiation on salary) and discuss equity. If an agreement is reached, we prepare an offer letter. If not, we consider one of the other final-round candidates.
  13. Once the candidate has signed and we have received the offer letter, HR will notify the other final round candidates.

Read Laurie's blog post on hiring for all the things not to do. The remainder of this section assumes you've read this post.

We are looking for people who:

npm values transparency and humanity, so as much as possible our interviews are transparent and humane. Interviews are inherently uncomfortable and scary, and nobody sounds smart when they are uncomfortable and scared. Do your best to compensate for this. If you think the candidate is doing well, be liberal about saying so. If the candidate makes a mistake, try to prevent them spiraling into meltdown by moving on quickly or giving positive feedback about some other aspect of their performance.

Your interview should be a conversation. You are not trying to prove that you know more about a topic than they do. You are not trying to quiz them to make sure they know everything about a specific topic or technology. You want to know if they can grasp complex concepts and explain them clearly, because that is what a knowledge worker does.

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.

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

Last modified February 02, 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!

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 January 08, 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 January 08, 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 January 08, 2016           Found a typo? Send a pull request!

npm On-Site Prerequisites

To install the latest version of npm On-Site, you need a server fulfilling these basic specs:

If using Amazon Web Services, see note on AWS below.

We have tested extensively on the operating systems listed above. It may be possible to run npm On-Site on other systems, but, at this time, no other systems are officially supported.

We do our best to support as many systems as possible. If you have special requirements or feedback for other platforms, please reach out to us at support@npmjs.com. We'd love to work with you.

You can also check for system issues on the npmo-installer GitHub repo.

The amount of disk space needed is directly proportional to the number and size of packages your registry will need to host.

For example, the full public registry hosts at least 200,000 packages with an average of 6 versions each, and this requires at least half a terabyte of storage. Smaller registries, however, can get away with just a few gigabytes.

Therefore, a server with 50 - 100 GB is a good choice for most registries.

Please reserve at least 6 GB for OS resources and npm On-Site appliance containers.

Once installed, you can configure where registry data is stored on your server via the "Storage" paths on the "Settings" page of the admin web console (port 8800). For details on configuring your On-Site instance, please see this page.

We recommend using an m3.large instance type.

If extra storage is needed, you may want to attach an EBS volume to your EC2 instance and configure the "Storage" paths on your On-Site appliance to use directories under the mount point.

To open ports on your AWS EC2 instance, you can define a Security Group with the following Inbound settings:

AWS Security Group

Last modified February 11, 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 January 08, 2016           Found a typo? Send a pull request!

npm-root

npm root [-g]

Print the effective node_modules folder to standard out.

Last modified January 08, 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.

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 January 21, 2016           Found a typo? Send a pull request!

Running npm On-Site in AWS

npm On-Site allows you to run your own private npm registry and website behind the firewall. It is designed to run on several different infrastructures. One of the easiest ways to run it, which we test extensively, is using Amazon Web Services. In this article, we'll show you exactly how to set this up.

Here's the general idea:

  1. Define a Security Group
  2. Launch an EC2 instance
  3. Format and mount an attached EBS volume
  4. Install and configure npm On-Site
  5. Use your private registry

That's all it takes to get up and running!

So let's start by logging into the AWS Console. From there, click on "EC2" in the top left to access the EC2 Dashboard.

In AWS, a private virtual server is called an "EC2 instance". We will need to create, or "launch", an instance that can run npm On-Site. Before we can launch an instance, however, we'll need a "security group" to allow inbound TCP communication on the ports the npm On-Site services will listen on. An AWS security group is a set of rules defining what type of network traffic is allowed for an EC2 instance.

To create a security group, first click "Security Groups" under "NETWORK & SECURITY" in the vertical navigation bar on the left. Then click the blue "Create Security Group" button near the top.

Security Group List

The ports needed for inbound traffic include:

Port | Reason           
---- | -----------------
8080 | Registry         
8081 | Website          
8082 | Auth endpoints   
8800 | Admin web console

Also note you will need SSH access to your instance, so include port 22 in your security group. Give your security group a name that you will recognize later, like "npmo":

Security Group Inbound

In a production environment, you will probably want to front the registry and website with a load balancer or routing layer that uses a DNS name and standard ports (80 for HTTP and 443 for HTTPS), but for purposes of this walkthrough we'll do without that initially and just access the services directly on the ports they bind to.

Now that we have a security group defined, we are ready to launch an EC2 instance.

Click on "Instances" under "INSTANCES" in the left navigation panel, and then click the blue "Launch Instance" button.

Instance List

This will start the multi-step instance wizard. The first step is to select a base Amazon Machine Image (or AMI) to start from. npm On-Site supports Ubuntu 14+, CentOS 7, and RHEL 7. For this walkthrough, we'll assume CentOS 7. You can use the top "centos 7" search result in the "AWS Marketplace". Just make sure it's 64-bit. Click the blue "Select" button.

Launch Step 1

The next step is to choose an instance type, which determines how many resources your server will be allocated with. We recommend using an m3.large type. Select the radio button in the first column of the table and click the "Next: Configure Instance Details" button on the bottom right.

Launch Step 2

Go with default instance details and click the "Next: Add Storage" button on the bottom right.

Launch Step 3

The next step is to configure storage volumes for your instance. We recommend adding an EBS volume that has at least 50 GB. We will use this volume to store the data for our npm On-Site registry, and using EBS will make it easy to create snapshots of your package data for backup or transfer purposes.

Click the "Add New Volume" button, select "EBS" as the "Volume Type", and enter your desired amount of storage in "Size". Then click the "Next: Tag Instance" button on the bottom right.

Launch Step 4

Give your instance a name and click the "Next: Configure Security Group" button.

Launch Step 5

Choose "Select an existing security group" at the top and then select the Security Group you created in step 1 from the list. Then click the blue "Review and Launch" button.

Launch Step 6

Review your settings and click the blue "Launch" instance when you are satisfied. This will open a dialog to select or create a key pair that you will need to access your instance over SSH.

Launch Step 7

In the dialog, select "Create a new key pair" if you do not already have one. Give it a name and click the "Download Key Pair" button. Remember where you save this file as you will need it to SSH into your server. Once you have downloaded the PEM key pair file, click the blue "Launch Instances" button.

Key Pair

Wait for your instance to launch, and view its status in the Instances list.

Instance Created

Note that if you're running your EC2 instance in a private AWS VPC, then you may need to explicitly set your network interface MTU setting to 1500. You can read about why and how to do this in the AWS docs.

Now that we have a server instance up and running, we need to prepare our attached EBS volume for use. Note that it will be attached but not formatted or mounted initially.

Access your server using the PEM key pair file via SSH. For Mac or Linux users, use the canonical ssh CLI program. For Windows users, try PuTTY. You can find the public IP for your server in the Instances list. Note that for CentOS 7, the username is centos, but if you chose a different AMI the username may be different (e.g. ubuntu for Ubuntu, ec2-user for RHEL, or admin for Debian).

$ ssh -i ~/.ssh/my-key-pair.pem centos@<public-ip>

First find the volume's device name, e.g. /dev/xvdb, using the lsblk command:

$ lsblk
NAME    MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
xvda    202:0    0   8G  0 disk
└─xvda1 202:1    0   8G  0 part /
xvdb    202:16   0  50G  0 disk

Let's quickly verify that our volume does not yet have a file system:

# sudo file -s <device> 
$ sudo file -s /dev/xvdb
/dev/xvdb: data

The output should say data, meaning there is no file system formatted on the volume yet. Let's add one:

# sudo mkfs -t ext4 <device> 
$ sudo mkfs -t ext4 /dev/xvdb
mke2fs 1.42.9 (28-Dec-2013)
Filesystem label=
OS type: Linux
Block size=4096 (log=2)
Fragment size=4096 (log=2)
Stride=0 blocks, Stripe width=0 blocks
3276800 inodes, 13107200 blocks
655360 blocks (5.00%) reserved for the super user
First data block=0
Maximum filesystem blocks=2162163712
400 block groups
32768 blocks per group, 32768 fragments per group
8192 inodes per group
Superblock backups stored on blocks:
	32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208,
	4096000, 7962624, 11239424
 
Allocating group tables: done                            
Writing inode tables: done                            
Creating journal (32768 blocks): done
Writing superblocks and filesystem accounting information: done

Now we can create a mount point, like /data, for our formatted volume:

# sudo mkdir <mount_point> 
$ sudo mkdir /data

Then we can mount the volume to the mount point and check it with the df -h command:

# sudo mount <device> <mount_point> 
$ sudo mount /dev/xvdb /data
$ df -h
Filesystem      Size  Used Avail Use% Mounted on
/dev/xvda1      8.0G  823M  7.2G  11% /
devtmpfs        3.6G     0  3.6G   0% /dev
tmpfs           3.5G     0  3.5G   0% /dev/shm
tmpfs           3.5G   17M  3.5G   1% /run
tmpfs           3.5G     0  3.5G   0% /sys/fs/cgroup
/dev/xvdb        50G   53M   47G   1% /data

So far, so good. In order to preserve the mount on reboot, we need to add an entry to fstab like so:

# keep the original fstab config in case we mess up 
sudo mv /etc/fstab /etc/fstab.orig
# copy the original fstab config 
sudo cp /etc/fstab.orig /etc/fstab
# and modify the new fstab config 
sudo vi /etc/fstab

Note that on CentOS we're using vi to edit the file. On other systems, you might be able to use nano instead.

With the file open, add an entry under the last line. In vi, go to the last line by hitting Shift + G and go to the end of the line with Shift + 4. Then insert a new line by hitting i to enter insert mode, use the right arrow key to move the end of the line and press Enter to add a new line as shown below (only the second line). On CentOS or RHEL, use defaults,nofail as the fs mount options; on Ubuntu or Debian, use defaults,nofail,nobootwait.

#<device>  <mount_point> <fs_type> <fs_mount_ops>   <fs_freq> <fs_passno> 
/dev/xvdb  /data         ext4      defaults,nofail  0         2

In vi, exit insert mode with the Escape key and save and exit by entering :wq.

Now we should test our new fstab config. This command should give no output if everything is ok:

$ sudo mount -a

Let's make sure we have proper file permissions on our new mount point, and let's create a new directory there that will house all of our registry data:

$ sudo chown -R $(whoami):$(id -gn) /data
$ mkdir /data/npmo

Our EBS volume is now ready to go, and we can install Node.js and npm On-Site!

In this step, the walkthrough will follow standard installation, but we'll hit the highlights.

First install Node.js and update npm. Note that this command is specific to CentOS or RHEL:

$ curl -sL https://rpm.nodesource.com/setup_4.x | sudo -E bash -
$ sudo yum -y install nodejs
$ sudo npm install npm@latest -g

Then install npmo and answer any prompts:

$ sudo npm install npmo -g --unsafe

Once that is done, complete the installation by configuring your On-Site instance via the admin web console at https://<your-server>:8800. At this point we will defer to the installation doc, with the exception that we should configure our storage settings to use our mounted EBS volume.

When you reach the Settings page, find the "Storage" section and change the /usr/local/lib/npme path prefix to /data/npmo for all configured paths:

Storage Settings

For testing purposes, you may want to select "Open" as the "Authentication" option.

Once your configuration settings are saved, you will be prompted to start the registry components and go to the Dashboard view. All the components will be downloaded and started as lightweight containers. Once you see a status of "Started", your registry is ready for use!

Started

Back at the terminal prompt of your local machine, let's configure your npm CLI client to use your new private registry.

Authenticate with your registry and associate the registry to a scope name. The scope is a namespace or prefix that you will use for your private packages.

$ npm login --registry http://<your-server>:8080 --scope @demo

Now whenever npm sees the @demo scope in a package name, like @demo/test-pkg, it will automatically publish to or install from your private npm On-Site registry.

To quickly verify this, let's create a tiny module and publish it as a private package:

$ mkdir test-pkg
$ cd test-pkg
$ npm init -y --scope @demo
$ echo "module.exports = 'test successful'\n" > index.js
$ npm publish

Visit your registry's website at http://<your-server>:8081/ and find the @demo/test-pkg package under "recently updated packages".

Published

Now let's make sure we can install our private package:

$ mkdir downstream
$ cd downstream
$ npm install @demo/test-pkg
$ node -e "console.log(require('@demo/test-pkg'))"
test successful

As you can see, your package was downloaded to a local node_modules directory, allowing you to require() and use it.

So that's about it. Hopefully this demonstrated how easy it is to run your own private registry on AWS with npm On-Site.

For more advanced topics or questions, we encourage you to check out the rest of our docs or drop us a line at support@npmjs.com.

Happy publishing and installing!

Last modified February 11, 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, 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.

Scoped packages are supported by the public npm registry. The npm client is backwards-compatible with un-scoped registries, so it can be used to work with scoped and un-scoped 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 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 is just specifying to require the module mypackage in the folder called @myorg.

Scoped packages can be published to any registry that supports them, including the public npm registry.

(As of 2015-04-19, the public 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 public 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 08, 2016           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 <pkg> <stage>. Pre and post commands with matching names will be run for those as well (e.g. premyscript, myscript, postmyscript).

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 January 08, 2016           Found a typo? Send a pull request!

npm-search

npm search [-l|--long] [search terms ...]

aliases: s, se

Search the registry for packages matching the search terms.

If a term starts with /, then it's interpreted as a regular expression. A trailing / will be ignored in this case. (Note that many regular expression characters must be escaped or quoted in most shells.)

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.

Last modified January 08, 2016           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 On-Site 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 November 29, 2015           Found a typo? Send a pull request!

npm Security Policy

Outlined in this document are the practices and policies that npm applies to help ensure that we release stable/secure software, and react appropriately to security threats when they arise.

  1. Reporting Security Problems to npm
  2. Security Point of Contact
  3. Onboarding Developers
  4. Separation of Duties and Authorization
  5. Critical Updates And Security Notices
  6. Responding to Security Threats
  7. Vulnerability Scanning
  8. Password Policies
  9. Application Design Best Practices
  10. Development Process
  11. AntiVirus Software

If you need to report a security vulnerability. Please contact us or email security@npmjs.com.

We review all security reports within one business day. Note that the npm staff is generally offline for most US holidays, but please do not delay your report! Our off-hours support staff can fix many issues, and will alert our security point of contact if needed.

npm's CTO Laurie Voss is the current point of contact for all security related issues.

Any emails sent to security@npmjs.com will be escalated to the security point of contact, who will delegate incident response activities as appropriate.

All new technical hires are introduced to our security policy as part of the onboarding process.

We learn about critical software updates and security threats from a variety of sources:

Along with keeping an eye out for critical security updates, automatic security updates are enabled on all of our production servers allowing patches to be applied immediately without human intervention.

https://help.ubuntu.com/community/AutomaticSecurityUpdates

When a security threat is identified, we have the following process in place:

  1. We have the slack channel security-all, which is used to prioritize and coordinate responses to security threats.
  2. Our Security Point of Contact oversees this discussion: managing the triage, responding to emails, and updating npm's status page.
  3. Based on the triage, work is allocated to developers to address the threat:

Along with reacting to security notifications as they happen, we proactively pen-test and audit software.

We perform regular penetration testing and code audits with the security firm Lift Security.

While working on features at npm, all engineers coordinate security audits with the Security Point of Contact.

Documents from this process are available, and can be provided to customers when requested.

The cloud hosting platforms that we use provide options for automated vulnerability scanning.

We should opt for alternative authentication methods when possible:

SSH keys should be rolled out selectively, providing developers access to only the severs that they require access to.

In the next section of the document, we discuss the design methodologies that we use to build stable and secure software.

Logs are important for both debugging applications and detecting security breaches in our software -- ask CJ for a speech about logging.

All applications should contain logging for date, time, operation, and a unique request identifier.

We use common-log-string internally to standardize this:

At least 90 days of logs should be kept for each service. On high traffic hosts this may require backing-up logs in cloud storage on a regular basis.

On the servers that we manage for other companies, we should audit logs on a regular basis.

TODO: We plan to build automated anomaly detection systems in place for our logs see internal issue #381.

Logs should not contain any sensitive user information, e.g., passwords.

The module hide-secrets is used to help with this.

Micro-services should only have access to databases and files that they need access to.

With our docker-based infrastructure (npm On-Site) this is achieved by having containers only mount folders on the root host that they require access to.

In our production environment, this is achieved by partitioning services across multiple hosts.

Security-groups, or Zones in the case of SoftLayer, are used to limit the network connectivity between hosts.

When deploying a service, ask: "what other services does this actually need to connect to?"

Any sensitive user information should be encrypted at rest. Using encrypted EBS drives, or an equivalent, is a great way to achieve this.

Communication between services on the same host can be performed via HTTP.

All inter-service communication between two hosts is performed using TLS.

npm has a well-defined, security-focused, development process:

No code goes into production unless it is reviewed by at least one other developer.

The onus is on the reviewer to ask hard questions: "what are the ramifications of opening up port-X?", "why is this connection being made over HTTP instead of HTTPS?"

We love testing at npm:

The design process, and management techniques vary from team to team at npm. Across the board, however, we strive to have continuous deployments. Releasing many small features as they become production ready.

Security is taken into account during all phases of the software development life-cycle: unit tests think about potential threats; when testing on staging, we attempt to test potential exploits, etc.

On our managed Ubuntu hosts, we run the ClamAV AntiVirus software.

The infected server should be retired, and a new server should be provisioned from scratch.

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.

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

Last modified February 02, 2016           Found a typo? Send a pull request!

semver

$ npm install semver

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

As a command-line utility:

$ semver -h

Usage: semver <version> [<version> [...]] [-r <range> | -i <inc> | --preid <identifier> | -l | -rv]
Test if version(s) satisfy the supplied range(s), and sort them.

Multiple versions or ranges may be supplied, unless increment
option is specified.  In that case, only a single version may
be used, and it is incremented by the specified level

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

If no versions are valid, or ranges are not satisfied,
then exits failure.

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

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

Hyphen Ranges X.Y.Z - A.B.C

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.

X-Ranges 1.2.x 1.X 1.2.* *

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 January 08, 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": "1.1.0",
  "dependencies": {
    "B": {
      "version": "1.0.1",
      "from": "B@^1.0.0",
      "resolved": "https://registry.npmjs.org/B/-/B-1.0.1.tgz",
      "dependencies": {
        "C": {
          "version": "1.0.1",
          "from": "org/C#v1.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.

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

Since npm shrinkwrap is intended to lock down your dependencies for production use, devDependencies will not be included unless you explicitly set the --dev flag when you run npm shrinkwrap. If installed devDependencies are excluded, then npm will print a warning. If you want them to be installed with your module by default, please consider adding them to dependencies instead.

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 08, 2016           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 January 08, 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 January 08, 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 January 08, 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 January 08, 2016           Found a typo? Send a pull request!

npm-tag

[DEPRECATED] npm tag <name>@<version> [<tag>]
See `dist-tag`

THIS COMMAND IS DEPRECATED. See npm-dist-tag for details.

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

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 always sets the "latest" tag to the published version.

Tags can be used to provide an alias instead of version numbers. For example, npm currently uses the tag "next" to identify the upcoming version, and the tag "latest" to identify the current version.

A project might choose to have multiple streams of development, e.g., "stable", "canary".

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 January 08, 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 January 08, 2016           Found a typo? Send a pull request!

Term and Licenses

npm, Inc. offers software and services under a few different licenses and terms of use.

License terms and notices for the npm command-line program can be found in the LICENSE file of the project's source code at https://www.github.com/npm/npm.

npmjs.com and Other npm Services

The npm Open Source Terms at https://www.npmjs.com/policies/open-source-terms govern use of https://www.npmjs.com and the npm public registry.

The npm Private Packages Terms at https://www.npmjs.com/policies/private-terms govern use of npm Private Packages.

The npm Personal Payment Plan https://www.npmjs.com/policies/personal-plan and the npm Organization Payment Plan https://www.npmjs.com/policies/organization-plan govern payment for npm Private Packages.

Last modified February 02, 2016           Found a typo? Send a pull request!

npm-test

  npm test [-- <args>]
  npm tst [-- <args>]

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

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

Last modified January 08, 2016           Found a typo? Send a pull request!

npm Trademark Policy

npm is a package manager for Node.js modules. It was created in 2009 by Isaac Schlueter as an open source project to help JavaScript developers share modules (aka packages) of code in a very easy and efficient way.

The npm project contains two main parts:

  1. The npm client, which is bundled with the Node.js platform, and is used as a command line tool to install and publish packages. It is simply called "npm". Its code is available as an open-source project: https://github.com/npm/npm
  2. The npm registry service. When a user of the npm client runs the command npm install example-package, the npm client retrieves the package and all related dependencies from the npm registry service. The example output looks like this:
user1-MacBook-Pro-2:~ user1$ npm install example-package
npm http GET https://registry.npmjs.org/example-package
npm http 200 https://registry.npmjs.org/example-package
example-package@2.4.1 node_modules/example-package

The registry is run as a free (as in beer) public service for anyone wanting to publish an open source package and for anyone to install an open source package.

npm, Inc. is a company co-founded by npm's creator, Isaac 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, Inc. has filed for trademarks for the npm name and logo. We have developed this trademark usage policy with the following goals in mind:

Nominative use - No need to type ™ on twitter

It's perfectly OK to use "npm" to refer to npm, Inc., to the npm software, and to the npm public registry. That's different from using npm in the name of one's own product or service.

Nominative use means it's OK to refer to something that is trademarked, but it is not OK to incorporate one company's trademark into another company's product, service, or company name. That's why you would need permission from the trademark owner to open "Discount Nike Shoes" or "iPad App Marketplace".

We ask that you get permission from npm, Inc. to use the npm name or logo as part of the name of any project, product, service, domain or company.

We will grant permission to use the npm name and logo for projects that meet the following criteria:

For other projects, we have set up the following rules around the use of the npm trademark:

  1. It is not OK use npm in the name of any product, service, or project, except after the preposition "for". For example, "Private Registry Hosting for npm". You should not use npm in a company or domain name for a package registry or related service without our permission.
  2. When referring to the npm software in body text, the first usage should be followed by a generic term such as "package manager" to provide context. npm should never be used or explained as an acronym.
  3. When referring to the npm public registry, please follow npm with the word "registry" or the phrase "public registry".
  4. When referring to a private registry for npm packages, please describe it as "private registry for npm packages" or as a npm-registry proxy when first referring to it in the text.
  5. References to the owner of the npm client software and the operator of the npm public registry should be to npm, Inc.
  6. Any materials referring to npm should include the following notice in the fine print: "npm is a trademark of npm, Inc."

Examples of ways to use the term "npm" in a name

An example of a way to refer to npm when describing your solution:

When in doubt about your use of the npm name or logo, please contact npm, Inc. for clarification.

Our npm Logo is very recognizable and deserves special treatment. The npm Logo signifies us, or a special relationship with us, and you should use it only with our permission. Since the goal is to avoid confusion about you being us, or your relationship with us, context counts. We will consider requests on a case-by-case basis.

Like the npm Logo, the npm Wombat graphic is a very recognizable part of the npm brand, and signifies a special relationship with the the npm project, service, or company. It should never be used except with explicit written permission. We will consider requests on a case-by-case basis.

Please be advised that, unlike the npm logo, the Wombat generally may not be used to refer to the project, service, or company in a nominative sense, as any usage will almost always imply a special relationship with npm.

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 February 02, 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 January 08, 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 January 08, 2016           Found a typo? Send a pull request!

npm-update

npm update [-g] [<pkg>...]

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 Infinity update, but be warned that simultaneous asynchronous update of all packages, including npm itself and packages that npm depends on, often causes problems up to and including the uninstallation of npm itself.

To restore a missing npm, use the command:

curl -L https://npmjs.com/install.sh | sh

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)

Recording Updates with --save

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 January 29, 2016           Found a typo? Send a pull request!

To update npm On-Site, simply click Check Now in the admin console.

Last modified November 29, 2015           Found a typo? Send a pull request!

Private, scoped modules

Lots of companies using Node.js love the "many small modules" pattern that is part of the Node culture. However, splitting internal applications and private code up into small modules has been inconvenient, requiring git dependencies or other workarounds to avoid publishing sensitive code to the public registry. npm On-Site makes private modules a first-class citizen.

npm On-Site requires a 2.x+ version of the npm client. You can get this by running

[sudo] npm install npm -g

Once you have an up-to-date client, log in to your registry using your GitHub or GitHub Enterprise credentials:

npm login --registry=http://myreg.mycompany.com:8080 --scope=@myco

Now you can install private modules without any additional work, the same way you do with public modules:

npm install @myco/somepackage

npm automatically knows that any package with the @myco scope should be installed from your npm On-Site installation. Scoped packages will be installed into your node_modules folder and can be used in your JavaScript just like any other module:

require('@myco/somepackage');

Publishing private modules is similarly easy. Simply give your package name a scope in package.json:

{
  "name": "@myco/anypackage"
}

Then publish as usual:

npm publish

npm will automatically publish to your npm On-Site, and will refuse to publish scoped packages to the public registry.

Last modified November 29, 2015           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.

Last modified January 21, 2016           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 January 29, 2016           Found a typo? Send a pull request!

npm Weekly

Did you miss one? Check out the npm weekly archive.

Last modified November 29, 2015           Found a typo? Send a pull request!

npm-whoami

npm whoami [--registry <registry>]

Print the username config to standard output.

Last modified January 08, 2016           Found a typo? Send a pull request!

Getting Started

How npm works

Private Modules

Organizations

Using npm

npm On-Site

CLI Commands

Configuring npm

npm policy documents

View All On One Page