npmjs.com

All Docs

What is npm?

npm opens up an entire world of JavaScript talent for you and your team. It's the world's largest software registry, with approximately 3 billion downloads per week. The registry contains over 600,000 packages (building blocks of code). Open-source developers from every continent use npm to share and borrow packages, and many organizations use npm to manage private development as well.

Here is a quick introduction to npm:

npm consists of three distinct components:

Use the website to discover packages, set up profiles, and manage other aspects of your npm experience. For example, you can set up Orgs (organizations) to manage access to public or private packages.

The CLI runs from a terminal. This is how most developers interact with npm.

The registry is a large public database of JavaScript software and the meta-information surrounding it.

Use npm to . . .

These are just a few examples of ways developers use npm. If you'd like to add a bullet point, comment here.

Where do I Start?

Now that you know what npm is, and a bit about how to use it, it's time to get started.

Your First Package Page

First, you create an npm account, which is explained in the next chapter. You will then have you own page on npmjs.com, which will be http://www.npmjs.com/~yourusername.

As you publish packages, they will appear on your page. You can add organizations to invite others to work with you.

After you set up an npm account, the next step is to use the commmand line interface (CLI) to install npm. We look forward to seeing what you create!

How do I share packages or collaborate with others?

If you choose to share your packages publicly, there is no cost. To use and share private packages, you need to upgrade your account. To share with others, create organizations, called npm Orgs, and invite others to work with you, privately (for a fee) or publicly (for free). Or you can sign up for a custom, private type of npm for your company, called npmE for npm Enterprise.

Learn more about npm Orgs and npmE

npm Orgs provide tools for managing both public and private packages. Granting permissions is easy, and configuration is simplified.

If you would prefer to have your own private registry, so that you can develop packages internally that are not shared publicly, consider npm Enterprise.

Learn More

To learn more about npm as a product, new features on the way, and interesting uses of npm, sign up for our newsletter at npm-weekly, and be sure to follow @npmjs on twitter.

To explore additional features and options, click here.

To learn about tools to manage multiple packages and collaborators, see npm Orgs.

To learn more about npm Enterprise, click here.

For mentoring, tutorials, and learning, vist node school. Consider attending or hosting a nodeschool event (usually free!) at a site near you, or use the self-help tools you can find on the site.

CLI Reference Doc / Online Help

While relevant CLI commands are covered throughout this user documentation, the CLI includes command line help, its own documentation section, and instant help (man pages). When you click a doc about any CLI command, a list of all CLI commands appears in the left-hand side bar. You can also access the list of CLI commands by scrolling to CLI Commands on the docs home page.

Last modified March 21, 2018           Found a typo? Send a pull request!

Finding and Selecting Packages

To find packages, start with the npm search bar.

Example: Finding a Package

You want to use bar codes (QR codes) in your application. Rather than spend weeks figuring out how to do this, why not see if someone has posted a package that creates QR codes? Start by entering a value in the search bar:

As you type, possible choices appear:

How to Choose Between Similar Packages

After entering a search term in the search bar, press Enter to see rankings that will help you choose between similar packages:

Often, there are dozens or even hundreds of packages with similar names and/or similar purposes. To help you decide the best ones to explore, each package has been ranked according to four criteria using the npms analyzer:

Popularity indicates how many times the package has been downloaded. This is a good indicator of packages that others have found to be especially useful, but not foolproof.

Quality includes considerations such as the presence of a readme file, stability, tests, up-to-date dependencies, custom website, and code complexity.

Maintenance ranks packages according to the attention given by developers. Packages that are maintained more frequently are more likely to work well with the current or upcoming versions of npm, for example.

Optimal combines the three other criteria in a meaningful way.

To list packages according to a specific criteria, click its label under Sort Packages. For example, to search by Popularity, click Popularity.

The Package Page

When you choose a package, more information appears. This information is written by the package author(s) so details vary. This is where you can discover how to use this package. Developers often provide contact information as well.

Here are some examples of the type of information you will find on the package page.

Parts of the Package Page:

These are the tabs available on the package page.

Viewing Readme

The readme file is created by the package developer. If done well, it explains the purpose of the package, and how to use it.

Viewing Dependencies

Many packages are made up of other packages. These packages are called dependencies.

Viewing Dependents

Packages that incorporate the package shown in some way are called dependents.

Viewing Versions

When a package is updated, a list of previous versions appear.

Download a package

The next chapter explains how to install npm. After you install npm, you will use a terminal console to download packages. This is explained in later chapters.

Learn More

For more information about how npms and the npms analyzer work, click here.

Last modified March 21, 2018           Found a typo? Send a pull request!

Getting started

  1. Create an account from npmjs.com.

  2. Install npm from a terminal console.

  3. Login to the terminal with your new username.

Note: Many of the steps that you can take from the browser can also be taken directly from the Command Line Interface. Skip here to learn more.

Create an account

  1. Go to http://www.npmjs.com and click 'log in'.
  1. Complete the sign up page.

Full Name First and Last Name. (You can enter middle name(s) as well).

Public Email Enter an email account. This email address will be added to the metadata when you publish a package. This means that the email address can be discovered by anyone who downloads your packages. In addition, npm will send email to this acccount when you update packages, as well as occassional product updates and information.

Username Enter the username that will be shown when you publish packages or interact with other users within npm. Choose a name that doesn't violate our policy guidelines. The name must be lower case. It can have dashes and numerals, but there are restrictions in order to prevent fake accounts.

Password Follow the password guidelines on the screen.

  1. Click the two boxes according to your wishes. Then click `Create an Account'.

  2. Open the email address that you entered.

  3. Find a message with the title Welcome to npm (search All Mail in case the email doesn't appear in the inbox).

The welcome message has links to helpful resources; you might want to flag it for later reference.

Note: If you can't find the welcome message, please click to resend:

  1. Click the link in your email. Success! You will be sent to your new landing page.

Notice the URL:

https://www.npmjs.com/~yourusername

This is a quick way to get to your page in the future.

After you set up your Login Account

You now have a login account. Here are a few things you can do before (or after) you install npm:

Or you can install npm in the terminal console, as explained below, then come back to these steps.

The following screen shot shows where the menu is if you want to explore the website, set up your profile, and get started right away:

Terminals, Editors, and Git (For Beginners)

Skip this section if you've worked with terminals or editors in the past.

At npm, we are thrilled to welcome many brand new coders to the javascript world. Before you begin using npm, you need to know about setting up a terminal, an editor, and git. Welcome!

First:

  1. Find the terminal emulator for your computer:

  2. Find and pick a text editor that you like.

  3. Consider signing up for a git account account if you haven't already.

There are additional resources for beginners and for everyone at the end of this chapter in the "Learn More" section.

Install npm & manage npm versions

npm is written in Node.js, so you need to install Node.js in order to use npm. You can install npm via the Node.js website, or by installing a Node Version Manager or NVM. This chapter explains both options.

If you just want to get started exploring npm, using the Node.js installation method is fastest. If you are an advanced developer ready to jump in and work with versions, use the node version manager. If you aren't sure, please read this chapter before you decide. You can always change how you run npm in the future.

Installing npm from the Node.js site

1. Install Node.js & npm

OS/X or Windows

If you're using OS X or Windows, use one of the installers from the Node.js download page. Be sure to install the version labeled LTS. Other versions have not yet been tested with npm.

Linux

If you're using Linux, choose one of these options:

Less-common operating systems

Click here to learn about installing node.js for a variety of operating systems.

2. Test your installation

After installing, run node -v. The version should be v8.9.1 or higher.

3. Update npm

When you install node.js, npm is automatically installed. However, npm gets updated more frequently than Node.js, so be sure that you have the latest version.

To test, run npm -v.

To be sure that this matches the latest version, scroll to the bottom of this page. If the version you see does not match the latest version, run:

npm install [email protected] -g.

This will install the latest official, tested version of npm.

Using a version manager to install Node.js and npm

Since npm and node.js products are managed by different entities, updates and maintenance can become complex. Also, the Node.js installation process installs npm in a directory that only has local permissions. This can cause permissions errors when you attempt to run packages globally.

To solve both these issues, many developers opt to use a node version manager, or nvm, to install npm. The version manager will avoid permissions errors, and will solve the complexities of updating Node.js and npm.

In addition, developers can use an nvm to test their applications on multiple versions of npm. The nvm enables you to easily switch npm as well as node versions. This makes it easier to ensure that your applications work for most users, even if they are using other versions of npm. If you decide to install a version manager, use the instructions for the version manager you select to learn how to switch versions, and to learn how to keep up-to-date with the latest version of npm.

Apple macOS

Click here to learn how to install nvm for MacOs.

Microsoft Windows

To install and manage npm and Node.js on Windows, we suggest nvm-windows.

Linux

Click here to learn how to install nvm for Linux.

Login to npm from a terminal

To test your new account, type:

npm login

You will be promted for your username, password, and email. Be sure to spell your username exactly the same way as you entered it on the website, or you will create a new account.

npmlogin

If you have already set up two-factor authentication, you will be asked for a one-time password when you login. Please see the chapter about two-factor authentication if you need more information.

To test that you have successfully logged in, type npm whoami.

Experimenting with the next release

For more advanced users

If you want to try the next, unreleased version of npm to test that packages you have created will work with the planned next release of npm, use this command:

npm install [email protected] -g

This may simply reinstall the current version, depending on the development cycle. Also, this early version is not final. So features may or may not match what is ultimately released.

Learn more

To learn more about how to use node version manager, nvm, click here.

For tutorials, a chance to meet others, and step-by-steps, explore node school and its helpful site

See npm's Laurie Voss on "Stuff Everybody Knows Except You" if you are feeling overwhelmed in your dev learning. It will make you realize you are not alone!

How to use Apple's terminal Terminal.

How to use Microsoft Windows PowerShell.

How to find a Linux terminal emulators.

Note: While relevant CLI commands are covered throughout this user documentation, the CLI includes command line help, its own documentation section, and instant help (man pages).

Last modified June 04, 2018           Found a typo? Send a pull request!

How to Install Local Packages

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

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

Installing a Package

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.

Test:

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.

Example:

Install a package called lodash. Confirm that it ran successfully by listing the contents of the node_modules directory, where you should see a directory called lodash.

Microsoft Windows:

C:\ npm install lodash
C:\ dir node_modules

#=> lodash

macOS, Ubuntu, Debian

> npm install lodash
> ls node_modules             

#=> lodash

Which Version of the Package is Installed?

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

If there is a package.json file, npm installs the latest version that satisfies the semver rule declared in package.json.

Using the Installed Package in Your Code

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.

Example:

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

Working with package.json

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

A package.json file:

Requirements

A package.json must have:

For example:

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

Creating a package.json

There are two basic ways to create a package.json file.

1. Run a CLI questionnaire

To create a package.json with values that you supply, run:

> npm init

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

2. Create a default package.json

To get a default package.json, run npm init with the --yes or -y flag:

> npm init --yes

This method will generate a default package.json using information extracted from the current directory.

> npm init --yes
Wrote to /home/ag_dubs/my_package/package.json:

{
  "name": "my_package",
  "description": "",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/ashleygwilliams/my_package.git"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "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 "[email protected]"
> npm set init.author.name "ag_dubs"
> npm set init.license "MIT"

NOTE:

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 when searching npm, so it's definitely useful to make a custom description in the package.json to make your package easier to find.

How to Customize the package.json questionnaire

If you expect to create many package.json files, you might wish to customize the questions asked during the init process, so that the files always contain key information that you expect. You can customize the fields as well as the questions that are asked.

To do this, you create a custom .npm-init.js in your home directory ~/.npm-init.js.

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

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

Running npm init with this file in your home directory would output a package.json that included these lines:

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

You can also customize the questions by using the prompt function.

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

To learn more about how to create advanced customizations, check out the docs for init-package-json

Specifying Dependencies

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:

Manually editing your package.json

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 that name the packages you'd like to use. It will point to a semver expression that specifies the versions of that project that are compatible with your project.

If you have dependencies you only need to use during local development, follow the same instructions as above but use the 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-prod 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-prod (assumed by default) 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-prod]

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

npm install <package_name> --save-dev

Managing dependency versions

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, npm will look at the dependencies that are listed in that file and download the latest versions, using semantic versioning.

Learn More

To understand more about the power of package.json, see the video "Installing npm packages locally" which you can find in Chapter 4.

To learn more about semantic versioning, see Getting Started "Semver" page.

Last modified June 11, 2018           Found a typo? Send a pull request!

How to Update Local Packages

It's a good practice to periodically update the packages your application depends on. Then, if the original developers have improved their code, your code will be improved as well.

To do this:

  1. run npm update in the same directory as the package.json file of the application that you want to update.
  2. Run npm outdated. There should not be any results.

Learn More

Last modified December 22, 2017           Found a typo? Send a pull request!

How to Uninstall Local Packages

To remove a package from your node_modules directory, use:

npm uninstall <package>:

npm uninstall lodash

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

npm uninstall --save lodash

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

Test:

To confirm that npm uninstall worked correctly, find the node_modules directory. Be sure that it no longer contains a directory for the package(s) you uninstalled.

You can do this by running:

Example:

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

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

Install Lodash
> npm install lodash
> dir node_modules               # use `ls node_modules` for Unix
Uninstall Lodash
#=> lodash

> npm uninstall lodash
> dir node_modules               # use `ls node_modules` for Unix

#=>

Last modified December 22, 2017           Found a typo? Send a pull request!

How to Install Global Packages

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

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

npm install -g jshint

If you get an EACCES error, see this chapter about permissions.

Tip: Consider using npx to run packages globally, if you have npm 5.2 or greater installed.

Last modified March 21, 2018           Found a typo? Send a pull request!

How to Update Global Packages

Requires version 2.6.1 or greater. See below if you are using an older version.

To update global packages, type:

npm update -g <package>

For example, to update a package called jshint, you'd type:

npm update -g jshint

To find out which packages need to be updated, type:

npm outdated -g --depth=0

To update all global packages, type:

npm update -g

If you are using version 2.6.0 or less

For npm versions less than 2.6.1, run this script to update all outdated global packages.

However, please consider upgrading to the latest version of npm. To do this, type:

npm install [email protected] -g

Last modified June 04, 2018           Found a typo? Send a pull request!

How to uninstall global packages

To uninstall a global package,type:

npm uninstall -g <package>

To uninstall a package called jshint, you would type:

npm uninstall -g jshint

Last modified December 22, 2017           Found a typo? Send a pull request!

How to Create Node.js Modules

Node.js modules are a type of package that can be published to npm. To create a new module, start by creating a package.json file.

Use npm init to create package.json. It will prompt you for values for fields. The two required fields are 'name' and 'version'. You'll also need to set a value for 'main'. You can use the default, index.js. These steps are described in detail in Chapter 5.

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

Your Name <[email protected]> (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. The default name for this file 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.
  3. Switch to the new directory (cd)
  4. Run npm install <package>.
  5. Create a test.js file which requires the package and calls the method.
  6. Run node test.js. The message sent to the console.log should appear.

Learn More

To understand types of packages, click here.

Last modified December 22, 2017           Found a typo? Send a pull request!

How to Publish & Update a Package

You can publish any directory that has a package.json file. This chapter explains how to publish a package for the first time, and how to update it later.

How to Publish a Package

Preparation

Understand npm policies

Before you begin, it's a good idea to review npm's policies, in case you have questions about site etiquette, naming, licensing, or other guidelines.

Create a User Account

To publish, you must be a user on the npm registry. If you aren't a user, create an account by using npm adduser. If you created a user account on the site, use npm login to access your account from your terminal.

Test:

  1. Type npm whoami from a terminal to see if you are already logged in (technically, this also means that your credentials have been stored locally).

  2. Check that your username has been added to the registry at https://npmjs.com/~username.

For example,

https://www.npmjs.com/~carolynawombat

Review the Package Directory

Review the Contents

Note that everything in the directory will be included unless it is ignored by a local .gitignore or .npmignore file. To learn how to use these commands, see npm-developers.

Review the package.json File

Read Working with package.json to be sure that the details you want are reflected in your package.

Choose a name

Choose a unique name for your package. Try to choose a descriptive name that:

Note: The first 3 caveats don't apply if you are using scopes.

Include Documentation (readme.md)

npm recommends that you include a readme file to document your package. The readme file must have the filename readme.md. The file extension .md indicates that the file is a markdown file. This file will appear on the npm website when someone finds your package.

Before you begin, please look at some of the package pages to get ideas for the information you can add to your readme file, and to see why this is so important.

  1. Create a file using any text editor.

  2. Save it in the project directory with the name readme.md

  3. When you publish, this documentation will display on the web page where people download your package.

Publish!

Use npm publish to publish the package.

Test

Go to https://npmjs.com/package/<package>. You should see a page all about your new package. It might look a bit like this:

Congratulations!

How to Update a Package

How to Update the Version Number

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: this will also add a tag with the updated release number to your git repository if you have linked one to your npm account.

After updating the version number, run npm publish again.

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

How to Update the Read Me File

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

Learn More

To find out more about node modules and packages, see here.

To learn about semantic versioning, click here.

To learn more about tags, click here.

To learn more about package.json files, click here.

To learn more about naming, including how npm protects you against typosquat confusion, click here

Last modified June 11, 2018           Found a typo? Send a pull request!

How to use Semantic Versioning

It's important to communicate the extent of changes in a new release of code, because sometimes updates can break code that a package needs (called dependencies).Semantic versioning (semver) is a standard that was designed to solve this problem.

Semver for Publishers

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:

SemVerTable

Semver for Consumers

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:

Learn More

For a great tool you can use to learn about how semver works with your favorite packages, see the npm semver calculator.

For more about using semantic versioning with package.json files, see Chapter 5.

For another way to label releases, learn about npm dist tags, and how they relate to semantic versioning.

Last modified March 21, 2018           Found a typo? Send a pull request!

How to Work with Scoped Packages

Requires npm version 2 or greater

Scopes are used to group related packages together, and to create a namespace, like a domain, for npm modules. This is explained in more detail here.

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

npm Orgs also have scopes.

@orgname/project-name

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

How to Initialize a Scoped Package

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

Publishing a Scoped Package

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

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

Using a Scoped Package

To use a scoped package, 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 docs.npmjs.com/private-modules/intro.

Last modified June 11, 2018           Found a typo? Send a pull request!

How to Label Packages with Dist-tags

Distribution tags (dist-tags) supplement semantic versioning (e.g., v0.12). Use them to organize and label different versions of packages. In addition to being more human-readable than semver numbering, tags allow publishers to distribute their packages more effectively.

Adding tags

To add a tag to a specific version of your package, use:

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

Publishing with tags

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

Installing with tags

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 [email protected]

Caveats

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

Learn More

See this CLI doc for more about tags. See Chapter 13 for more about semantic versioning.

Last modified December 22, 2017           Found a typo? Send a pull request!

How to Use Two-Factor Authentication

Requires npm version 5.5.1 or greater

Are you who you say you are? Let's double-check.

To meet the increasing need for strong digital security, npm introduced two-factor authentication (2FA) or (tfa) with version 5.5.1. Two-factor authentication prevents unauthorized access to your account by confirming your identity using two methods:

For example, if your bank uses 2FA, the first time you logged in to your online banking system, the bank sent a code to your cell phone number, then prompted you to enter the code online. This proved that the cell phone was in your possession, and linked it to your account for authentication. After that, whenever the bank detects anything unusual, such as a login from a different laptop, it will send a temporary code to your phone that you must enter before you can login. This provides an extra layer of security because, even if someone obtains your login credentials, they are unlikely to have your device in their possession as well. Even if someone finds your phone, they are unlikely to also be able to hack your laptop's password.

Two-factor authentication multiplies the protection against attacks, and we recommend that you implement this with your npm account.

Preparation

To enable 2FA with your npm account, you will need an application that can generate a One Time Password, or OTP. For example, Authy or Google Authenticator, can generate one time passwords (OTP's). These products use a Time-Based One-Time Password Algorithm (TOTP) to create temporary codes. Install the application on a mobile device or a second laptop that will always be available when you work in your npm account. (Note: npm does not use SMS (text-to-phone) as a method for authenticating users.)

Levels of Authentication

There are two levels of authentication, auth-only and auth-and-writes.

If you enable 2FA in auth-only mode, npm will require an OTP when you:

If you enable 2FA in auth-and-writes mode, which is the default, npm will require an OTP when you:

Also, see the table at the end of this chapter.

How Do I Enable 2FA?

To set up two-factor authentication, you can use either use:

Both approaches are explained in this chapter. Choose the method you like best.

Enabling 2FA from the web

Two-factor authentication is now available as a profile setting from the website.

  1. Login to npmjs.com.
  2. Click your avatar to see the options menu.
  1. Click Profile Settings.
  1. Scroll down to the Security section:
  1. Enter your password on the next page:
  1. On the next screen, choose the level of 2FA you want.

Note: If you aren't sure which setting you want, see the table at the end of this chapter.

  1. Click the plus sign to enable the level you want. (You can change the level later if you wish.)

A QR code will appear (in the screen shot, the code is masked for security reasons).

  1. Follow the instructions on the screen to scan the QR code, then enter it.

npm will display recovery codes. The recovery codes are what you will use to log in if you ever lose or forget your second factor device (for example, if you don't have your phone).

  1. Print, screen capture and save these recovery codes in a place that is not near your second factor device. Your password manager may provide a way to save these safely.

  2. After you have saved the recovery codes, press Go Back to return to your profile.

Success! You will see your Profile page, with a message confirming that you set up tfa, plus an indicator in the Security section of the page.

Enabling 2FA from the Command Line

Type the command that meets the level of security you wish to apply (auth-and-writes is the default).

    npm profile enable-2fa
    npm profile enable-2fa auth-and-writes 
    npm profile enable-2fa auth-only

npm will return this message:

   > npm notice profile Enabling two factor authentication for auth-and-writes   

or this message:

  > npm notice profile Enabling two factor authentication for auth-only

depending on the setting you provided.

Next, npm will display a QR code:

Masked QR Code And Prompt

  1. Add a new account to your authenticator app.
  2. Scan the QR code, or enter the number displayed just below the QR code.

This will configure the authenticator app for future use, linking authentication to the device that generated the authentication.

Using your authenticator app, enter an OTP at the prompt shown:

    Add an OTP code from your authenticator:

After you have entered the one-time password, npm will display this message:

2FA successfully enabled. 
Below are your recovery codes, please print these out. 
You will need these to recover access to your account 
if you lose your authentication device.

After you have applied two-factor authentication, you can use the npm profile get command to confirm that it has been set.

Profile After 2FA Enabled

Example: Setting Profile Values from the CLI after Enabling 2FA

Once you have installed 2FA, you will need to enter an OTP for security-relevant commands. For example, whenever you use the command npm profile set you will need to enter an OTP before you can set or change a value, such as your fullname:

$npm profile set fullname Carolyn A. Wombat
Enter OTP: 567452
Set fullname to Carolyn A. Wombat

Use `npm profile get' to confirm the new setting.

Profile After Adding Setting

Note to our readers: We have reset the account used in screen shots; neither the QR nor the codes are still active. But thank you to those alert and kind wombats who have asked us about this.

How to add an OTP to a command

To add the OTP to a command, append it as shown:

npm owner add <user > --otp=123456

Recovery Codes

After you set up two-factor authentication, a series of recovery codes will appear on your screen. Please print them and save them as described. Note: Some authenticator applications and password management applications provide a method for you to store recovery codes.

Tip: Save recovery codes in a different location than the device you use to authenticate. For example, if you get your OTP from a tablet, don't save the codes in a case with your tablet.

The recovery procedure is explained below.

How to Remove Two-Factor Authentication from your Profile

To remove 2FA from your profile, type this command:

    npm profile disable-2fa

npm will prompt for your password:

    > npm password:   

Enter your npm password as prompted, then npm will display:

   >Enter one-time password from your authenticator: 123456

npm will confirm:

   Two factor authentication disabled.   

How to Send an OTP Value from the Command Line

If you have enabled 2FA auth-and-writes, you will need to send the OTP from the command line for certain commands to work. To do this, append --otp=123456 (where 123456 is the code generated by your authenticator) at the end of the command. Here are a few examples:

npm publish [<tarball>|<folder>][--tag <tag>] --otp=123456
npm owner add <user > --otp=123456
npm owner rm <user> --otp=123456
npm dist-tags add <pkg>@<version> [<tag>] --otp=123456
npm access edit [<package>) --otp=123456
npm unpublish [<@scope>/]<pkg>[@<version>] --otp=123456

What to Do if You Misplace Your Second Device

If you cannot locate the device that provided second-factor authentication:

  1. Find the recovery codes you saved when you enabled 2FA.
  2. If you are logged out, login normally using your login and npm password. When prompted for an OTP, enter a recovery code. (Note that this might create a second authenticator account with the same npm account name. Be sure to use the newly created account.)
  3. Once you are logged in, type npm profile disable-2fa and enter your npm password if prompted.
  4. Enter an unused recovery code when you see this prompt:
 >Enter one-time password from your authenticator: 
  1. npm will confirm that two-factor authentication has been disabled.
  2. type npm profile enable-2fa to re-enable 2FA, assign a different device to your account, and generate new recovery codes.

If you have misplaced your recovery codes, please contact npm customer support.

What if You See an Error after Entering the OTP?

If you are entering what seems to be a valid OTP but you see an error, be sure that you are using the correct authenticator account. In the screen shot below, the current account in Authy was set incorrectly because the developer had multiple npm test accounts. This will cause the OTP to fail. Also, as stated earlier, when you reset 2fa after it has been disabled, the authenticator might create a second account with the same name. Please see the authenticator documentation to delete the old account.

Multiple Authenticator Accounts

When Will npm Require the Second Factor?

If you enable 2-factor authorization, you will need to enter the second factor at various points as you use npm. This table explains these details.

2nd Factor Table

Note

Settings you define using the Command Line Interface (CLI) will also apply to the website.

Last modified March 21, 2018           Found a typo? Send a pull request!

How to Work with Authentication Tokens

Requires npm version 5.5.1 or greater

Whenever you login to npm, an authentication token is generated. Tokens give you rights to publish and access your modules.

Because a token is simply a hexadecimal string, you can use the token in other tools, such as continuous integration testing environments, so that the tool can run with the access it needs to complete tasks. For example, Travis-CI provides an environment variable that you can assign to a token value. This gives Travis-CI the ability to run npm as your npm user, including the ability to install private packages to which you have access.

Read this chapter to learn how to manage security tokens.

Token commands empower you to:

Note: *There are additional steps required if you wish to use tokens for testing and other special purposes. Find more details here.

You can work with tokens from the web or the CLI, whichever is easiest. What you do in each environment will be reflected in the other environment.

Working with tokens from the web

To start go to the Tokens page.

  1. Login to the website.
  2. Choose Tokens from your Avatar User menu:

Or, if you are working in another tab on the web, you can click the Tokens tab:

Create a New Token

How to View the Tokens On Your Account

Working with tokens from the CLI

How to View the Tokens On Your Account

To view the tokens associated with your account, type:

npm token list.

npmtokenlist

The following table explains the token list.

tokenlisttable

A token can be both read-only and CIDR-whitelisted.

If you have enabled two-factor authentication on your profile, you have implemented an additional layer of security.

Note: The token list shows a truncated version of the token. View the npmrc file if you need to see the full token.

How to Create New Tokens

npm token create [--read-only] [--cidr=list]

Before you create a new token, decide which type of token you want:

The default setting for new tokens is full-permission.

When a token is read-only, it cannot be used to make changes to a package. If a token is not explicitly set to read-only, it has full permissions, including publish and modification rights.

How to Create a New Full-Permission token:

To create a new full permission token, type:

'npm token create'

If you have set up two-factor authentication, you will be prompted for your npm password, followed by an OTP. npm will display this table:

npmtokencreatelong

TIP: Save a screen shot of the token field, as this will be your only chance to view it.

Note that read-only defaults to false.

How to Create a New Read-Only Token

To create a new read-only token, type:

npm token create --read-only

If you have set up two-factor authentication, you will be prompted for an npm password, followed by an OTP. npm will display this table:

npmtokencreatereadonly

Note that read-only is set to true.

How to Create a New CIDR-Restricted Token

To limit the token so that it can only be used from specified ip addresses, you can create a CIDR-restricted token. CIDR is an acronym for Classless Inter-Domain Routing. The CIDR Wiki page will get you started.

Using a CIDR restriction makes it possible for you to force anyone or any system using the token to either physically or remotely be within the specified IP address range.

    npm token create --[--cidr=list]

example:

    npm token create --cidr=192.0.2.0/24

If you have set up two-factor authentication, you will be prompted for an npm password, followed by an OTP. npm will display this table:

npmtokencreatecidr

If you see a message like this one:

npm ERR! CIDR whitelist contains invalid CIDR entry: X.X.X.X./YY,Z.Z.. . .

(where the string returned is the one you entered) please ensure that the CIDR string is valid and in the appropriate format. Note: npm only supports IPv4 at this time.

How to Create a CIDR-Restricted Read-Only Token

To create a CIDR-restricted token that is also read-only, type:

npm token create --read-only --cidr=list

How to Revoke Tokens

You can delete (revoke) a token, regardless of when it was created. This allows you to gain control of access you may wish to take back.

The command to delete a token is:

npm token delete

Here are the steps:

  1. Type npm token list
  2. Find the token ID affiliated with the token you want to delete.
  3. Type 'npm token delete 123456', where 123456 is the token id. Note: The truncated version of the token will not work.
npm will report 'Removed 1 token'

Type 'npm token list' to confirm that the token has been removed.

The following screen shot demonstrates these steps:

npmtokenrevokeshort

Note: All tokens shown in screen illustrations have been revoked.

Note: In certain cases, there may be a delay of up to an hour before a token is successfully revoked. npm is currently working to make revocation occur immediately in all cases.

Learn More

For more information about using tokens with continuous integration testing, see this chapter.

Last modified June 11, 2018           Found a typo? Send a pull request!

npmjs.com has been updated. There are now new profile settings you can enable from the website, or, you can use the command line interface if you prefer.

Setting up Your Profile from the Web

To set up your profile on npmjs.com, login.

Choose Profile Settings from the Avatar menu. The profile page appears.

Starting from this page, you can:

How to Change Profile Settings from the CLI

Requires npm version 5.5.1 or greater.

To view and set profile properties from the Command Line Interface (CLI), use these commands:

npm profile get 
npm profile set <prop> <value>

Viewing & Setting Profile Values

To see your current profile settings, type:

npm profile get

npm displays your profile settings in a table:

You can set or modify the following profile properties from the command line:

How to Set a Password from the Command Line

To set a password, type:

npm profile set password

npm will prompt you for your current password, then you can set the new password.

The password must follow these guidelines:

These rules protect your password by making it difficult to guess.

How to Set Other Profile Properties

To set other values, append them to the end of the line as shown:

$npm profile set fullname nori pat marsupial

npm will prompt for credentials, including a one-time-password if you have enabled two-factor authentication. npm will then confirm that the change has occurred:

Set fullname to nori pat marsupial

Enabling and Disabling Two-Factor Authentication

Enable two-factor authentication if you would like to make it more difficult for attackers to gain access to your account and your publishing rights.

You can enable and disable two-factor authentication from the command line, or from the web, using the steps described here.

Notes

Please refer to the command line documentation for more details and examples.

Last modified May 24, 2018           Found a typo? Send a pull request!

Understanding Packages and Modules

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.

Quick Summary

What is a package?

A package is any of the following:

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

Git urls can be of the form:

git://github.com/user/project.git#commit-ish
git+ssh://[email protected]:project.git#commit-ish
git+http://[email protected]/project/blah.git#commit-ish
git+https://[email protected]/project/blah.git#commit-ish

The commit-ish can be any tag, sha, or branch which can be supplied as an argument to git checkout. The default is master.

What is a module?

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

Most npm packages are 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".

File and Directory Names in the Node.js and npm Ecosystem

So, why is it the node_modules folder, but package.json file? Why not node_packages or module.json?

The package.json file defines the package. (See "What is a package?", above.)

The node_modules folder is the place Node.js looks for modules. (See "What is a module?", above.)

For example, if you create a file at node_modules/foo.js and then had a program that did var f = require('foo.js'), 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 December 22, 2017           Found a typo? Send a pull request!

How to Prevent Permissions Errors

If you see an EACCES error when you try to install a package globally, read this chapter. This error can often be avoided if you change the directory where npm is installed. To do this, either:

  1. Reinstall npm with a version manager (recommended),

    or

  2. Change npm's default directory manually.

Option One: Reinstall with a Node Version Manager

This is the best way to avoid permissions issues. This is described in Chapter 2. You do not need to remove your current version of npm or Node.js before installing a node version manager.

Option Two: Change npm's Default Directory

This section does not apply to Microsoft Windows. This chapter will be updated to address Windows in the near future.

To minimize the chance of permissions errors, you can configure npm to use a different directory. In this example, it will be a hidden directory on your home folder.

  1. Back-up your computer before you start.

  2. Make a directory for global installations:

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

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

     export PATH=~/.npm-global/bin:$PATH
    
  5. 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 use the corresponding ENV variable (e.g. if you don't want to modify ~/.profile):

    NPM_CONFIG_PREFIX=~/.npm-global

Tip: Consider npx

If you are using npm version 5.2 or greater, explore npx as an alternative way to run global commands, especially if you just need a command occassionally. Click here to read an excellent article about npx.

Last modified June 11, 2018           Found a typo? Send a pull request!

About security audits

A security audit is an assessment of package dependencies for security vulnerabilities. Security audits help you protect your package's users by enabling you to find and fix known vulnerabilities in dependencies that could cause data loss, service outages, unauthorized access to sensitive information, or other issues.

Running a security audit with npm audit

Note: The npm audit command is available in [email protected] To upgrade, run npm install [email protected] -g.

The npm audit command submits a description of the dependencies configured in your package to your default registry and asks for a report of known vulnerabilities. npm audit checks direct dependencies, devDependencies, bundledDependencies, and optionalDependencies, but does not check peerDependencies.

npm audit automatically runs when you install a package with npm install. You can also run npm audit manually on your locally installed packages to conduct a security audit of the package and produce a report of dependency vulnerabilities and, if available, suggested patches.

  1. On the command line, navigate to your package directory by typing cd path/to/your-package-name and pressing Enter.
  2. Ensure your package contains package.json and package-lock.json files.
  3. Type npm audit and press Enter.
  4. Review the audit report and run recommended commands or investigate further if needed.

Resolving EAUDITNOPJSON and EAUDITNOLOCK errors

npm audit requires packages to have package.json and package-lock.json files.

Reviewing and acting on the security audit report

Running npm audit will produce a report of security vulnerabilities with the affected package name, vulnerability severity and description, path, and other information, and, if available, commands to apply patches to resolve vulnerabilities. For more information on the fields in the audit report, see "About audit reports"

Security vulnerabilities found with suggested updates

If security vulnerabilities are found and updates are available, you can either:

SEMVER warnings

If the recommended action is a potential breaking change (semantic version major change), it will be followed by a SEMVER WARNING. If the package with the vulnerability has changed its API, you may need to make additional changes to your package's code.

Security vulnerabilities found requiring manual review

If security vulnerabilities are found, but no patches are available, the audit report will provide information about the vulnerability so you can investigate further.

To address the vulnerability, you can

Check for mitigating factors

Review the security advisory in the "More info" field for mitigating factors that may allow you to continue using the package with the vulnerability in limited cases. For example, the vulnerability may only exist when the code is used on specific operating systems, or when a specific function is called.

Update dependent packages if a fix exists

If a fix exists but packages that depend on the package with the vulnerability have not been updated to include the fixed version, you may want to open a pull or merge request on the dependent package repository to use the fixed version.

  1. To find the package that must be updated, check the "Path" field for the location of the package with the vulnerability, then check for the package that depends on it. For example, if the path to the vulnerability is @package-name > dependent-package > package-with-vulnerability, you will need to update dependent-package.
  2. On the npm public registry, find the dependent package and navigate to its repository. For more information on finding packages, see "How to find and select packages".
  3. In the dependent package repository, open a pull or merge request to update the version of the vulnerable package to a version with a fix.
  4. Once the pull or merge request is merged and the package has been updated in the npm public registry, update your copy of the package with npm update.

Fix the vulnerability

If a fix does not exist, you may want to suggest changes that address the vulnerability to the package maintainer in a pull or merge request on the package repository.

  1. Check the "Path" field for the location of the vulnerability.
  2. On the npm public registry, find the package with the vulnerability. For more information on finding packages, see "How to find and select packages".
  3. In the package repository, open a pull or merge request to make the fix on the package repository.
  4. Once the fix is merged and the package has been updated in the npm public registry, update your copy of the package that depends on the package with the fix.

Open an issue in the package or dependent package issue tracker

If you do not want to fix the vulnerability or update the dependent package yourself, open an issue in the package or dependent package issue tracker.

  1. On the npm public registry, find the package with the vulnerability or the dependent package that needs an update. For more information on finding packages, see "How to find and select packages".
  2. In the package or dependent package issue tracker, open an issue and include information from the audit report, including the vulnerability report from the "More info" field.

No security vulnerabilities found

If no security vulnerabilities are found, this means that packages with known vulnerabilities were not found in your package dependency tree. Since the advisory database can be updated at any time, we recommend regularly running npm audit manually, or adding npm audit to your continuous integration process.

Turning off npm audit on package installation

Installing a single package

To turn off npm audit when installing a single package, use the --no-audit flag:

npm install example-package-name --no-audit

For more information, see the npm-install command.

Installing all packages

To turn off npm audit when installing all packages, set the audit setting to false in your user and global npmrc config files:

npm set audit false

For more information, see the npm-config management command and the npm-config audit setting.

Last modified May 24, 2018           Found a typo? Send a pull request!

About audit reports

Audit reports contain tables of information about security vulnerabilities in your project's dependencies to help you fix the vulnerability or troubleshoot further.

Vulnerability table fields

Severity

The severity of the vulnerability, determined by the impact and exploitability of the vulnerability in its most common use case.

Severity Recommended action
Critical Address immediately
High Address as quickly as possible
Moderate Address as time allows
Low Address at your discretion

Description

The description of the vulnerability. For example, "Denial of service".

Package

The name of the package that contains the vulnerability.

Patched in

The semantic version range that describes which versions contain a fix for the vulnerability.

Dependency of

The module that the package with the vulnerability depends on.

Path

The path to the code that contains the vulnerability.

More info

A link to the security report.

Last modified May 11, 2018           Found a typo? Send a pull request!

Working with private packages

To use private packages, you must run a version of npm greater than 2.7.0. You also must be a paid npm user.

With npm private packages, 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 packages like Express and Browserify side-by-side with your own private code.

Before we start

Log in to npm again after upgrading to the most recent version.

npm install -g npm
npm login

Setting up your package

All private packages are scoped.

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. If you create an npm Org, the orgname can be the scope. Orgs can be free or paid. Using a public Org is the only free way to use scopes in package names.

@username/project-name
@orgname/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

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.

Sharing access from the web

If you want to give access to someone, they need to be subscribed to private packages as well. Once they are, you can give them read or read-write access. Or, you can set up an npm Org to give them access through Orgs and teams. Please refer to the online npm Orgs book for details.

To give someone access without using an org, navigate to the package page. You can find it at:

https://www.npmjs.com/package/your-package-name

To control access to the package click the + button under Collaborators .

Add the appropriate username, then click Submit.

Sharing access from the CLI

You can also add collaborators on the command line:

npm owner add <user> <package name>

Installing private packages

To install a private packages, 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')

Working with Org Scopes

Please refer to the Orgs book for details about how to create and assign teams, and work with Orgs scopes.

Switching from private to public

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

You can also manage package access via the command line:

npm access restricted <package_name>

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

Last modified March 21, 2018           Found a typo? Send a pull request!

Downloading packages to CI/deployment servers

If you are using deployment servers or testing with Continuous Intergration servers, you'll need a way to download your private packages to those servers. These are the steps:

How to create a new authentication token

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, use npm token create.

$ npm token create
npm password:

┌────────────────┬──────────────────────────────────────┐
│ token          │ d97a6e1f-cb87-0000-94e0-e06fe03c8a5c │
├────────────────┼──────────────────────────────────────┤
│ cidr_whitelist │                                      │
├────────────────┼──────────────────────────────────────┤
│ readonly       │ false                                │
├────────────────┼──────────────────────────────────────┤
│ created        │ 2018-03-14T21:57:25.427Z             │
└────────────────┴──────────────────────────────────────┘

There are several settings that you can use in the new token. Please see this doc for details.

Setting up a project-specific .npmrc file

Set up a custom .npmrc file in your project folder. Use this to authenticate the CI or deployment server with npm.

Setting up environment variables

To make this more secure when pushing it up to the server, you can set this token as an environment variable on the server.

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

Checking in your .npmrc

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

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

How to Invalidate a Token

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.

`npm token revoke' is a better choice. For instructions, see.

Last modified March 21, 2018           Found a typo? Send a pull request!

Docker and private packages

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

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

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

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

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

Runtime Variables

If you had the following Dockerfile:

FROM risingstack/alpine:3.3-v4.3.1-3.0.1

COPY package.json package.json  
RUN npm install

# Add your source files
COPY . .  
CMD npm start  

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

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

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

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

Build-time variables

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

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

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

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

FROM risingstack/alpine:3.3-v4.3.1-3.0.1

ARG NPM_TOKEN  
COPY .npmrc .npmrc  
COPY package.json package.json  
RUN npm install  
RUN rm -f .npmrc

# Add your source files
COPY . .  
CMD npm start

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

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

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

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

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

Last modified February 17, 2018           Found a typo? Send a pull request!

Try the latest stable version of node

If you're experiencing issues while using a version of node which is unsupported or unstable (odd numbered versions e.g. 0.7.x, 0.9.x, 0.11.x), it's very possible your issue will be fixed by simply using the LTS version of node.

See what version of node you're running:

node -v

Updating node on Linux

For some Linux distributions (Debian/Ubuntu and RedHat/CentOS), the latest node version provided by the distribution may lag behind the stable version. Here are instructions from NodeSource on getting the latest node.

Updating node on Windows

Install the latest msi from https://nodejs.org/download

Updating node on OSX

Install the latest package from https://nodejs.org/download

or if you are using homebrew

brew install node

An easy way to stay up-to-date

Node.js has lots of versions, and its development is very active. As a good practice to manage the various versions, we recommend that you use a version manager for your Node.js installation. There are many great options, here are a few:

Last modified March 21, 2018           Found a typo? Send a pull request!

Try the latest stable version of npm

See what version of npm you're running:

npm -v

Upgrading on *nix (OSX, Linux, etc.)

(You may need to prefix these commands with sudo, especially on Linux, or OS X if you installed Node using its default installer.)

You can upgrade to the latest version of npm using:

npm install -g [email protected]

Or upgrade to the most recent release:

npm install -g [email protected]

Upgrading on Windows

Microsoft wrote a small command line tool to automate the steps below. You can go and download it here - or stick with the manual path outlined below.


By default, npm is installed alongside node in

C:\Program Files (x86)\nodejs

npm's globally installed packages (including, potentially, npm itself) are stored separately in a user-specific directory (which is currently

C:\Users\<username>\AppData\Roaming\npm).

Because the installer puts

C:\Program Files (x86)\nodejs

before

C:\Users\<username>\AppData\Roaming\npm

on your PATH, it will always use the version of npm installed with node instead of the version of npm you installed using npm -g install [email protected]<version>.

To get around this, you can do one of the following:

cd %ProgramFiles%\nodejs
npm install [email protected]

If you installed npm with the node.js installer, after doing one of the previous steps, do the following.

(See also the point below if you're running Windows 7 and don't have the directory %appdata%\npm.)

A brief note on the built-in Windows configuration

The Node installer installs, directly into the npm folder, a special piece of Windows-specific configuration that tells npm where to install global packages. When npm is used to install itself, it is supposed to copy this special builtin configuration into the new install. There was a bug in some versions of npm that kept this from working, so you may need to go in and fix that up by hand. Run the following command to see where npm will install global packages to verify it is correct.

npm config get prefix -g

If it isn't set to <X>:\Users\<user>\AppData\Roaming\npm, you can run the below command to correct it:

npm config set prefix "${APPDATA}/npm" -g

Incidentally, if you would prefer that packages not be installed to your roaming profile (because you have a quota on your shared network, or it makes logging in or out from a domain sluggish), you can put it in your local app data instead:

npm config set prefix "${LOCALAPPDATA}/npm" -g

...as well as copying %APPDATA%\npm to %LOCALAPPDATA%\npm (and updating your %PATH%, of course).

Everyone who works on npm knows that this process is complicated and fraught, and we're working on making it simpler. Stay tuned.

Last modified March 21, 2018           Found a typo? Send a pull request!

If your npm is broken

Reinstall npm.

If you're on Windows and you have a broken installation, the easiest thing to do is to reinstall node from the official installer (see this note about installing the latest stable version).

Last modified March 21, 2018           Found a typo? Send a pull request!

Try clearing the npm cache

Sometimes npm's cache gets confused. You can reset it using:

npm cache clean --force

Last modified June 04, 2018           Found a typo? Send a pull request!

Common Errors

Random Errors--One Place to Start

No compatible version found

You have an outdated npm. Please update to the latest stable npm.

Permissions Errors

Please see the discussions in Chapter 2 and Chapter 3 about ways to avoid permissions errors.

Error: ENOENT, stat 'C:\Users\<user>\AppData\Roaming\npm' on Windows 7

This is a consequence of joyent/node#8141, and is an issue with the Node installer for Windows. The workaround is to ensure that C:\Users\<user>\AppData\Roaming\npm exists and is writable with your normal user account.

No space

npm ERR! Error: ENOSPC, write

You are trying to install on a drive that either has no space, or has no permission to write.

No git

npm ERR! not found: git
ENOGIT

You need to install git. Or, you may need to add your git information to your npm profile. You can do this from the command line or from the website.

running a Vagrant box on Windows fails due to path length issues

@drmyersii went through what sounds like a lot of painful trial and error to come up with a working solution involving Windows long paths and some custom Vagrant configuration:

This is the commit that I implemented it in, but I'll go ahead and post the main snippet of code here:

config.vm.provider "virtualbox" do |v|
    v.customize ["sharedfolder", "add", :id, "--name", "www", "--hostpath", (("//?/" + File.dirname(__FILE__) + "/www").gsub("/","\\"))]
end
 
config.vm.provision :shell, inline: "mkdir /home/vagrant/www"
config.vm.provision :shell, inline: "mount -t vboxsf -o uid=`id -u vagrant`,gid=`getent group vagrant | cut -d: -f3` > www /home/vagrant/www", run: "always"

In the code above, I am appending \\?\ to the current directory absolute path. This will actually force the Windows API to allow an increase in the MAX_PATH variable (normally capped at 260). Read more about max path. This is happening during the sharedfolder creation which is intentionally handled by VBoxManage and not Vagrant's "synced_folder" method. The last bit is pretty self-explanatory; we create the new shared folder and then make sure it's mounted each time the machine is accessed or touched since Vagrant likes to reload its mounts/shared folders on each load.

npm only uses git: and ssh+git: URLs for GitHub repos, breaking proxies

@LaurentGoderre fixed this with some Git trickery:

I fixed this issue for several of my colleagues by running the following two commands:

git config --global url."https://github.com/".insteadOf [email protected]:
git config --global url."https://".insteadOf git://

One thing we noticed is that the .gitconfig used is not always the one expected so if you are on a machine that modified the home path to a shared drive, you need to ensure that your .gitconfig is the same on both your shared drive and in c:\users\[your user]\

SSL Error

npm ERR! Error: 7684:error:140770FC:SSL routines:SSL23_GET_SERVER_HELLO:unknown protocol:openssl\ssl\s23_clnt.c:787:

You are trying to talk SSL to an unencrypted endpoint. More often than not, this is due to a proxy configuration error (see also this helpful, if dated, guide). In this case, you do not want to disable strict-ssl – you may need to set up a CA / CA file for use with your proxy, but it's much better to take the time to figure that out than disabling SSL protection.

npm ERR! Error: SSL Error: CERT_UNTRUSTED
npm ERR! Error: SSL Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE

This problem will happen if you're running Node 0.6. Please upgrade to node 0.8 or above. See this post for details.

You could also try these workarounds: npm config set ca "" or npm config set strict-ssl false

npm ERR! Error: SSL Error: SELF_SIGNED_CERT_IN_CHAIN

npm no longer supports its self-signed certificates

Either:

If this does not fix the problem, then you may have an SSL-intercepting proxy. (For example, https://github.com/npm/npm/issues/7439#issuecomment-76024878)

SSL-intercepting proxy

Unsolved. See https://github.com/npm/npm/issues/9282

Not found / Server error

npm http 404 https://registry.npmjs.org/faye-websocket/-/faye-websocket-0.7.0.tgz
npm ERR! fetch failed https://registry.npmjs.org/faye-websocket/-/faye-websocket-0.7.0.tgz
npm ERR! Error: 404 Not Found
npm http 500 https://registry.npmjs.org/phonegap

Invalid JSON

Error: Invalid JSON
npm ERR! SyntaxError: Unexpected token <
npm ERR! registry error parsing json

Many ENOENT / ENOTEMPTY errors in output

npm is written to use resources efficiently on install, and part of this is that it tries to do as many things concurrently as is practical. Sometimes this results in race conditions and other synchronization issues. As of npm 2.0.0, a very large number of these issues were addressed. If you see ENOENT lstat, ENOENT chmod, ENOTEMPTY unlink, or something similar in your log output, try updating npm to the latest version. If the problem persists, look at npm/npm#6043 and see if somebody has already discussed your issue.

cb() never called! when using shrinkwrapped dependencies

Take a look at issue #5920. We're working on fixing this one, but it's a fairly subtle race condition and it's taking us a little time. You might try moving your npm-shrinkwrap.json file out of the way until we have this fixed. This has been fixed in versions of npm newer than [email protected], so update to [email protected].

npm login errors

Sometimes npm login fails for no obvious reason. The first thing to do is to log in at https://www.npmjs.com/login and check that your e-mail address on npmjs.com matches the email address you are giving to npm login.

If that's not the problem, or if you are seeing the message "may not mix password_sha and pbkdf2", then

  1. Log in at https://npmjs.com/
  2. Change password at https://npmjs.com/password – you can even "change" it to the same password
  3. Clear login-related fields from ~/.npmrc – e.g., by running sed -ie '/registry.npmjs.org/d' ~/.npmrc
  4. npm login

and it generally seems to work.

See https://github.com/npm/npm/issues/6641#issuecomment-72984009 for the history of this issue.

npm hangs on Windows at addRemoteTarball

Check if you have two temp directories set in your .npmrc:

> npm config ls -l

Look for lines defining the tmp config variable. If you find more than one, remove all but one of them.

See https://github.com/npm/npm/issues/7590 for more about this unusual problem.

Why isn't npm running the latest version on my Windows machine?

See the section about Windows here.

Last modified June 04, 2018           Found a typo? Send a pull request!

npm-coding-style

Description

npm's coding style is a bit unconventional. It is not different for difference's sake, but rather a carefully crafted style that is designed to reduce visual clutter and make bugs more apparent.

If you want to contribute to npm (which is very encouraged), you should make your code conform to npm's style.

Note: this concerns npm's code not the specific packages that you can download from the npm registry.

Line Length

Keep lines shorter than 80 characters. It's better for lines to be too short than to be too long. Break up long lists, objects, and other statements onto multiple lines.

Indentation

Two-spaces. Tabs are better, but they look like hell in web browsers (and on GitHub), and node uses 2 spaces, so that's that.

Configure your editor appropriately.

Curly braces

Curly braces belong on the same line as the thing that necessitates them.

Bad:

function ()
{

Good:

function () {

If a block needs to wrap to the next line, use a curly brace. Don't use it if it doesn't.

Bad:

if (foo) { bar() }
while (foo)
  bar()

Good:

if (foo) bar()
while (foo) {
  bar()
}

Semicolons

Don't use them except in four situations:

Some examples of good semicolon usage:

;(x || y).doSomething()
;[a, b, c].forEach(doSomething)
for (var i = 0; i < 10; i ++) {
  switch (state) {
    case 'begin': start(); continue
    case 'end': finish(); break
    default: throw new Error('unknown state')
  }
  end()
}

Note that starting lines with - and + also should be prefixed with a semicolon, but this is much less common.

Comma First

If there is a list of things separated by commas, and it wraps across multiple lines, put the comma at the start of the next line, directly below the token that starts the list. Put the final token in the list on a line by itself. For example:

var magicWords = [ 'abracadabra'
                 , 'gesundheit'
                 , 'ventrilo'
                 ]
  , spells = { 'fireball' : function () { setOnFire() }
             , 'water' : function () { putOut() }
             }
  , a = 1
  , b = 'abc'
  , etc
  , somethingElse

Quotes

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"

Whitespace

Put a single space in front of ( for anything other than a function call. Also use a single space wherever it makes things more readable.

Don't leave trailing whitespace at the end of lines. Don't indent empty lines. Don't use more spaces than are helpful.

Functions

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

Callbacks, Sync/async Style

Use the asynchronous/non-blocking versions of things as much as possible. It might make more sense for npm to use the synchronous fs APIs, but this way, the fs and http and child process stuff all uses the same callback-passing methodology.

The callback should always be the last argument in the list. Its first argument is the Error or null.

Be very careful never to ever ever throw anything. It's worse than useless. Just send the error message back as the first argument to the callback.

Errors

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

Logging

Logging is done using the npmlog 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".

Case, naming, etc.

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.

null, undefined, false, 0

Boolean variables and functions should always be either true or false. Don't set it to 0 unless it's supposed to be a number.

When something is intentionally missing or removed, set it to null.

Don't set things to undefined. Reserve that value to mean "not yet set to anything."

Boolean objects are forbidden.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-config

Description

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

Command Line Flags

Putting --foo bar on the command line sets the foo configuration parameter to "bar". A -- argument tells the cli parser to stop reading flags. Using --flag without specifying any value will set the value to true.

Example: --flag1 --flag2 will set both configuration parameters to true, while --flag1 --flag2 bar will set flag1 to true, and flag2 to bar. Finally, --flag1 --flag2 -- bar will set both configuration parameters to true, and the bar is taken as a command argument.

Environment Variables

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

Notice that you need to use underscores instead of dashes, so --allow-same-version would become npm_config_allow_same_version=true.

npmrc Files

The four relevant files are:

See npmrc for more details.

Default Configs

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.

Shorthands and Other CLI Niceties

The following shorthands are parsed on the command-line:

If the specified configuration param resolves unambiguously to a known configuration parameter, then it is expanded to that configuration parameter. For example:

npm ls --par
# same as:
npm ls --parseable

If multiple single-character shorthands are strung together, and the resulting combination is unambiguously not some other configuration param, then it is expanded to its various component pieces. For example:

npm ls -gpld
# same as:
npm ls --global --parseable --long --loglevel info

Per-Package Config Settings

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

Config Settings

access

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.

allow-same-version

Prevents throwing an error when npm version is used to set the new version to the same value as the current version.

always-auth

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

also

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

audit

When "true" submit audit reports alongside npm install runs to the default registry and all registries configured for scopes. See the documentation for npm-audit for details on what is submitted.

auth-type

What authentication strategy to use with adduser/login.

bin-links

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

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

browser

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

ca

The Certificate Authority signing certificate that is trusted for SSL connections to the registry. Values should be in PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") 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.

cafile

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.

cache

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

cache-lock-stale

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

cache-lock-retries

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

cache-lock-wait

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

cache-max

DEPRECATED: This option has been deprecated in favor of --prefer-online.

--cache-max=0 is an alias for --prefer-online.

cache-min

DEPRECATED: This option has been deprecated in favor of --prefer-offline.

--cache-min=9999 (or bigger) is an alias for --prefer-offline.

cert

A client certificate to pass when accessing the registry. Values should be in PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with newlines replaced by the string "\n". For example:

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

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

cidr

This is a list of CIDR address to be used when configuring limited access tokens with the npm token create command.

color

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

This option can also be changed using the environment: colors are disabled when the environment variable NO_COLOR is set to any value.

depth

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

description

Show the description in npm search

dev

Install dev-dependencies along with packages.

dry-run

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.

editor

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

engine-strict

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

force

Makes various commands more forceful.

fetch-retries

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

fetch-retry-factor

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

fetch-retry-mintimeout

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

fetch-retry-maxtimeout

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

git

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.

git-tag-version

Tag the commit when using the npm version command.

commit-hooks

Run git commit hooks when using the npm version command.

global

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.

globalconfig

The config file to read for global config options.

global-style

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

group

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

heading

The string that starts all the debugging log output.

https-proxy

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

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.

ignore-prepublish

If true, npm will not run prepublish scripts.

ignore-scripts

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

init-module

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.

init-author-name

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

init-author-email

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

init-author-url

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

init-license

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

init-version

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

json

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

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

key

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

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

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

legacy-bundling

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.

link

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:

local-address

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.

loglevel

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

logstream

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.

logs-max

The maximum number of log files to store.

long

Show extended information in npm ls and npm search.

maxsockets

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

message

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

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

metrics-registry

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

node-options

Options to pass through to Node.js via the NODE_OPTIONS environment variable. This does not impact how npm itself is executed but it does impact how lifecycle scripts are called.

node-version

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

no-proxy

A comma-separated string or an array of domain extensions that a proxy should not be used for.

offline

Force offline mode: no network requests will be done during install. To allow the CLI to fill in missing cache data, see --prefer-offline.

onload-script

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

only

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.

optional

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

otp

This is a one-time password from a two-factor authenticator. It's needed when publishing or changing package permissions with npm access.

package-lock

If set to false, then ignore package-lock.json files when installing. This will also prevent writing package-lock.json if save is true.

When package package-locks are disabled, automatic pruning of extraneous modules will also be disabled. To remove extraneous modules with package-locks disabled use npm prune.

This option is an alias for --shrinkwrap.

package-lock-only

If set to true, it will update only the package-lock.json, instead of checking node_modules and downloading dependencies.

parseable

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

prefer-offline

If true, staleness checks for cached data will be bypassed, but missing data will be requested from the server. To force full offline mode, use --offline.

This option is effectively equivalent to --cache-min=9999999.

prefer-online

If true, staleness checks for cached data will be forced, making the CLI look for updates immediately even for fresh package data.

prefix

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

production

Set to true to run in "production" mode.

  1. devDependencies are not installed at the topmost level when running local npm install without any arguments.
  2. Set the NODE_ENV="production" for lifecycle scripts.

progress

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.

proxy

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.

read-only

This is used to mark a token as unable to publish when configuring limited access tokens with the npm token create command.

rebuild-bundle

Rebuild bundled dependencies after installation.

registry

The base URL of the npm package registry.

rollback

Remove failed installs.

save

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

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.

save-bundle

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

Makes sure that a package will be saved into dependencies specifically. This is useful if a package already exists in devDependencies or optionalDependencies, but you want to move it to be a production dep. This is also the default behavior if --save is true, and neither --save-dev or --save-optional are true.

save-dev

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.

save-exact

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

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.

save-prefix

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.

scope

Associate an operation with a scope for a scoped registry. Useful when logging in to a private registry for the first time: npm login [email protected] --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.

script-shell

The shell to use for scripts run with the npm run command.

scripts-prepend-node-path

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

If set to false, never modify PATH with that.

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

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

searchexclude

Space-separated options that limit the results from search.

searchopts

Space-separated options that are always passed to search.

searchlimit

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

searchstaleness

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

send-metrics

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

shell

The shell to run for the npm explore command.

shrinkwrap

If set to false, then ignore npm-shrinkwrap.json files when installing. This will also prevent writing npm-shrinkwrap.json if save is true.

This option is an alias for --package-lock.

sign-git-tag

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.

sso-poll-frequency

When used with SSO-enabled auth-types, configures how regularly the registry should be polled while the user is completing authentication.

sso-type

If --auth-type=sso, the type of SSO type to use.

strict-ssl

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

See also the ca config.

tag

If you ask npm to install a package and don't tell it a specific version, then it will install the specified tag.

Also the tag that is added to the [email protected] specified by the npm tag command, if no explicit tag is given.

tag-version-prefix

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.

timing

If true, writes an npm-debug log to _logs and timing information to _timing.json, both in your cache. _timing.json is a newline delimited list of JSON objects. You can quickly view it with this json command line: json -g < ~/.npm/_timing.json.

tmp

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

unicode

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

unsafe-perm

Set to true to suppress the UID/GID switching when running package scripts. If set explicitly to false, then installing as a non-root user will fail.

usage

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

user

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

userconfig

The location of user-level configuration settings.

umask

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.

user-agent

Sets a User-Agent to the request header

version

If true, output the npm version and exit successfully.

Only relevant when specified explicitly on the command line.

versions

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.

viewer

The program to use to view help content.

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-developers

Description

So, you've decided to use npm to develop (and maybe publish/deploy) your project.

Fantastic!

There are a few things that you need to do above the simple steps that your users will do to install your program.

About These Documents

These are man pages. If you install npm, you should be able to then do man npm-thing to get the documentation on a particular topic, or npm help thing to see the same information.

What is a package

A package is:

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://[email protected]:project.git#commit-ish
git+http://[email protected]/project/blah.git#commit-ish
git+https://[email protected]/project/blah.git#commit-ish

The commit-ish can be any tag, sha, or branch which can be supplied as an argument to git checkout. The default is master.

The package.json File

You need to have a package.json file in the root of your project to do much of anything with npm. That is basically the whole interface.

See package.json 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.

Keeping files out of your package

Use a .npmignore file to keep stuff out of your package. If there's no .npmignore file, but there is a .gitignore file, then npm will ignore the stuff matched by the .gitignore file. If you want to include something that is excluded by your .gitignore file, you can create an empty .npmignore file to override it. 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:

If, given the structure of your project, you find .npmignore to be a maintenance headache, you might instead try populating the files property of package.json, which is an array of file or directory names that should be included in your package. Sometimes a whitelist is easier to manage than a blacklist.

Testing whether your .npmignore or files config works

If you want to double check that your package will include only the files you intend it to when published, you can run the npm pack command locally which will generate a tarball in the working directory, the same way it does for publishing.

Link Packages

npm link is designed to install a development package and see the changes in real time without having to keep re-installing it. (You do need to either re-link or npm rebuild -g to update compiled packages, of course.)

More info at npm-link.

Before Publishing: Make Sure Your Package Installs and Works

This is important.

If you can not install it locally, you'll have problems trying to publish it. Or, worse yet, you'll be able to publish it, but you'll be publishing a broken or pointless package. So don't do that.

In the root of your package, do this:

npm install . -g

That'll show you that it's working. If you'd rather just create a symlink package that points to your working directory, then do this:

npm link

Use npm ls -g to see if it's there.

To test a local install, go into some other folder, and then do:

cd ../some-other-folder
npm install ../my-package

to install it locally into the node_modules folder in that other place.

Then go into the node-repl, and try using require("my-thing") to bring in your module's main module.

Create a User Account

Create a user with the adduser command. It works like this:

npm adduser

and then follow the prompts.

This is documented better in npm-adduser.

Publish your package

This part's easy. In the root of your folder, do this:

npm publish

You can give publish a url to a tarball, or a filename of a tarball, or a path to a folder.

Note that pretty much everything in that folder will be exposed by default. So, if you have secret stuff in there, use a .npmignore file to list out the globs to ignore, or publish from a fresh checkout.

Brag about it

Send emails, write blogs, blab in IRC.

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-disputes

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

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

TL;DR

  1. Get the author email with npm owner ls <pkgname>
  2. Email the author, CC [email protected]
  3. After a few weeks, if there's no resolution, we'll sort it out.

Don't squat on package names. Publish code or move out of the way.

Description

There sometimes arise cases where a user publishes a module, and then later, some other user wants to use that name. Here are some common ways that happens (each of these is based on actual events.)

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

  2. Yusuf writes an npm module foo, and publishes it. Perhaps much later, Alice finds a bug in foo, and fixes it. She sends a pull request to Yusuf, but Yusuf doesn't have the time to deal with it, because he has a new job and a new baby and is focused on his new Erlang project, and kind of not involved with node any more. Alice would like to publish a new foo, but can't, because the name is taken.

  3. Yusuf writes a 10-line flow-control library, and calls it foo, and publishes it to the npm registry. Being a simple little thing, it never really has to be updated. Alice works for Foo Inc, the makers of the critically acclaimed and widely-marketed foo JavaScript toolkit framework. They publish it to npm as foojs, but people are routinely confused when npm installfoo`` is some different thing.

  4. Yusuf writes a parser for the widely-known foo file format, because he needs it for work. Then, he gets a new job, and never updates the prototype. Later on, Alice writes a much more complete foo parser, but can't publish, because Yusuf's foo is in the way.

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

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

  7. After a reasonable amount of time, if Yusuf has not responded, or if Yusuf and Alice can't come to any sort of resolution, email support [email protected] and we'll sort it out. ("Reasonable" is usually at least 4 weeks.)

REASONING

In almost every case so far, the parties involved have been able to reach an amicable resolution without any major intervention. Most people really do want to be reasonable, and are probably not even aware that they're in your way.

Module ecosystems are most vibrant and powerful when they are as self-directed as possible. If an admin one day deletes something you had worked on, then that is going to make most people quite upset, regardless of the justification. When humans solve their problems by talking to other humans with respect, everyone has the chance to end up feeling good about the interaction.

EXCEPTIONS

Some things are not allowed, and will be removed without discussion if they are brought to the attention of the npm registry admins, including but not limited to:

  1. Malware (that is, a package designed to exploit or harm the machine on which it is installed).
  2. Violations of copyright or licenses (for example, cloning an MIT-licensed program, and then removing or changing the copyright and license statement).
  3. Illegal content.
  4. "Squatting" on a package name that you plan to use, but aren't actually using. Sorry, I don't care how great the name is, or how perfect a fit it is for the thing that someday might happen. If someone wants to use it today, and you're just taking up space with an empty tarball, you're going to be evicted.
  5. Putting empty packages in the registry. Packages must have SOME functionality. It can be silly, but it can't be nothing. (See also: squatting.)
  6. Doing weird things with the registry, like using it as your own personal application database or otherwise putting non-packagey things into it.
  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 [email protected] right away. You are never expected to resolve abusive behavior on your own. We are here to help.

TRADEMARKS

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

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

CHANGES

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.

LICENSE

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

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-orgs

Description

There are three levels of org users:

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

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

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

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

There are two main commands:

  1. npm team see npm-team for more details
  2. npm access see npm-access for more details

Team Admins create teams

npm team ls <org>:developers
npm team create <org:team>
npm team add <org:team> <user>

Publish a package and adjust package access

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

Monitor your package access

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-registry

Description

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

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

The official public npm registry is at 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.

Does npm send any information about me back to the registry?

Yes.

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

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

Can I run my own private registry?

Yes!

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

If you set up continuous replication from the official CouchDB, and then set your internal CouchDB as the registry config, then you'll be able to read any published packages, in addition to your private ones, and by default will only publish internally.

If you then want to publish a package for the whole world to see, you can simply override the --registry option for that publish command.

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

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

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

Will you replicate from my registry into the public one?

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

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

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

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

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-removal

Synopsis

So sad to see you go.

sudo npm uninstall npm -g

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

sudo make uninstall

More Severe Uninstalling

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

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

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-scope

Description

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

@somescope/somepackagename

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

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

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

Installing scoped packages

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

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

npm install @myorg/mypackage

Or in package.json:

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

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

Requiring scoped packages

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

require('@myorg/mypackage')

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

Publishing scoped packages

Scoped packages can be published from the CLI as of [email protected] and can be published to any registry that supports them, including the primary npm registry.

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

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

Publishing public scoped packages to the primary npm registry

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.

Publishing private scoped packages to the npm registry

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.

Associating a scope with a registry

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

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

npm login --registry=http://reg.example.com [email protected]

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.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-scripts

Description

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

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

PREPUBLISH AND PREPARE

DEPRECATION NOTE

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

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

USE CASES

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:

DEFAULT VALUES

npm will default some script values based on package contents.

USER

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

ENVIRONMENT

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

path

If you depend on modules that define executable scripts, like test suites, then those executables will be added to the PATH for executing the scripts. So, if your package.json has this:

{ "name" : "foo"
, "dependencies" : { "bar" : "0.1.x" }
, "scripts": { "start" : "bar ./test" } }

then you could run npm start to execute the bar script, which is exported into the node_modules/.bin directory on npm install.

package.json vars

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

configuration

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

Special: package.json "config" object

The package.json "config" keys are overwritten in the environment if there is a config param of <name>[@<version>]:<key>. For example, if the package.json has this:

{ "name" : "foo"
, "config" : { "port" : "8080" }
, "scripts" : { "start" : "node server.js" } }

and the server.js is this:

http.createServer(...).listen(process.env.npm_package_config_port)

then the user could change the behavior by doing:

npm config set foo:port 80

current lifecycle event

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

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

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

EXAMPLES

For example, if your package.json contains this:

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

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

EXITING

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

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

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

HOOK SCRIPTS

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

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

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

BEST PRACTICES

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

semver

Install

npm install --save semver

Usage

As a node module:

const semver = require('semver')
 
semver.valid('1.2.3') // '1.2.3'
semver.valid('a.b.c') // null
semver.clean('  =v1.2.3   ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7') // false
semver.lt('1.2.3', '9.8.7') // true
semver.valid(semver.coerce('v2')) // '2.0.0'
semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'

As a command-line utility:

$ semver -h

SemVer 5.3.0

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

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

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

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

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

-l --loose
        Interpret versions and ranges loosely

-c --coerce
        Coerce a string into SemVer if possible
        (does not imply --loose)

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

If no satisfying versions are found, then exits failure.

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

Versions

A "version" is described by the v2.0.0 specification found at http://semver.org/.

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

Ranges

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.

Prerelease Tags

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.

Prerelease Identifiers

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

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.

Tilde Ranges ~1.2.3 ~1.2 ~1

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

Caret Ranges ^1.2.3 ^0.2.5 ^0.0.4

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.

Range Grammar

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

Functions

All methods and classes take a final loose boolean argument that, if true, will be more forgiving about not-quite-valid semver strings. The resulting output will always be 100% strict, of course.

Strict-mode Comparators and Ranges will be strict about the SemVer strings that they parse.

Comparison

Comparators

Ranges

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.

Coercion

This aims to provide a very forgiving translation of a non-semver string to semver. It looks for the first digit in a string, and consumes all remaining characters which satisfy at least a partial semver (e.g., 1, 1.2, 1.2.3) up to the max permitted length (256 characters). Longer versions are simply truncated (4.6.3.9.2-alpha2 becomes 4.6.3). All surrounding text is simply ignored (v3.4 replaces v3.3.1 becomes 3.4.0). Only text which lacks digits will fail coercion (version one is not valid). The maximum length for any semver component considered for coercion is 16 characters; longer components will be ignored (10000000000000000.4.7.4 becomes 4.7.4). The maximum value for any semver component is Integer.MAX_SAFE_INTEGER || (2**53 - 1); higher value components are invalid (9999999999999999.4.7.4 is likely invalid).

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-access

Synopsis

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

Description

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.

DETAILS

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 you have two-factor authentication enabled then you'll have to pass in an otp with --otp when making access changes.

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.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-adduser

Synopsis

npm adduser [--registry=url] [[email protected]] [--always-auth] [--auth-type=legacy]

aliases: login, add-user

Description

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.

Configuration

registry

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

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

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 [email protected]

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

always-auth

Default: false

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

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

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

auth-type

What authentication strategy to use with adduser/login. Some npm registries (for example, npmE) might support alternative auth strategies besides classic username/password entry in legacy npm.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-audit

Synopsis

npm audit [--json]
npm audit fix [--force|--package-lock-only|--dry-run|--production|--only=dev]

EXAMPLES

Scan your project for vulnerabilities and automatically install any compatible updates to vulnerable dependencies:

$ npm audit fix

Run audit fix without modifying node_modules, but still updating the pkglock:

$ npm audit fix --package-lock-only

Skip updating devDependencies:

$ npm audit fix --only=prod

Have audit fix install semver-major updates to toplevel dependencies, not just semver-compatible ones:

$ npm audit fix --force

Do a dry run to get an idea of what audit fix will do, and also output install information in JSON format:

$ npm audit fix --dry-run --json

Scan your project for vulnerabilities and just show the details, without fixing anything:

$ npm audit

Get the detailed audit report in JSON format:

$ npm audit --json

Description

The audit command submits a description of the dependencies configured in your project to your default registry and asks for a report of known vulnerabilities. The report returned includes instructions on how to act on this information.

You can also have npm automatically fix the vulnerabilities by running npm audit fix. Note that some vulnerabilities cannot be fixed automatically and will require manual intervention or review. Also note that since npm audit fix runs a full-fledged npm install under the hood, all configs that apply to the installer will also apply to npm install -- so things like npm audit fix --package-lock-only will work as expected.

CONTENT SUBMITTED

SCRUBBING

In order to ensure that potentially sensitive information is not included in the audit data bundle, some dependencies may have their names (and sometimes versions) replaced with opaque non-reversible identifiers. It is done for the following dependency types:

The non-reversible identifiers are a sha256 of a session-specific UUID and the value being replaced, ensuring a consistent value within the payload that is different between runs.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-bin

Synopsis

npm bin [-g|--global]

Description

Print the folder where npm will install executables.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-bugs

Synopsis

npm bugs [<pkgname>]

aliases: issues

Description

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

Configuration

browser

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

registry

The base URL of the npm package registry.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-build

Synopsis

npm build [<package-folder>]

Description

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-bundle

Description

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

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-cache

Synopsis

npm cache add <tarball file>
npm cache add <folder>
npm cache add <tarball url>
npm cache add <name>@<version>

npm cache clean [<path>]
aliases: npm cache clear, npm cache rm

npm cache verify

Description

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

DETAILS

npm stores cache data in an opaque directory within the configured cache, named _cacache. This directory is a cacache-based content-addressable cache that stores all http request data as well as other package-related data. This directory is primarily accessed through pacote, the library responsible for all package fetching as of [email protected]

All data that passes through the cache is fully verified for integrity on both insertion and extraction. Cache corruption will either trigger an error, or signal to pacote that the data must be refetched, which it will do automatically. For this reason, it should never be necessary to clear the cache for any reason other than reclaiming disk space, thus why clean now requires --force to run.

There is currently no method exposed through npm to inspect or directly manage the contents of this cache. In order to access it, cacache must be used directly.

npm will not remove data by itself: the cache will grow as new packages are installed.

A NOTE ABOUT THE CACHE'S DESIGN

The npm cache is strictly a cache: it should not be relied upon as a persistent and reliable data store for package data. npm makes no guarantee that a previously-cached piece of data will be available later, and will automatically delete corrupted contents. The primary guarantee that the cache makes is that, if it does return data, that data will be exactly the data that was inserted.

To run an offline verification of existing cache contents, use npm cache verify.

Configuration

cache

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

The root cache folder.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-ci

Synopsis

npm ci

EXAMPLE

Make sure you have a package-lock and an up-to-date install:

$ cd ./my/npm/project
$ npm install
added 154 packages in 10s
$ ls | grep package-lock

Run npm ci in that project

$ npm ci
added 154 packages in 5s

Configure Travis to build using npm ci instead of npm install:

# .travis.yml
install:
- npm ci
# keep the npm cache around to speed up installs
cache:
  directories:
  - "$HOME/.npm"

Description

This command is similar to npm-install, except it's meant to be used in automated environments such as test platforms, continuous integration, and deployment. It can be significantly faster than a regular npm install by skipping certain user-oriented features. It is also more strict than a regular install, which can help catch errors or inconsistencies caused by the incrementally-installed local environments of most npm users.

In short, the main differences between using npm install and npm ci are:

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-completion

Synopsis

source <(npm completion)

Description

Enables tab-completion in all npm commands.

The synopsis above loads the completions into your current shell. Adding it to your ~/.bashrc or ~/.zshrc will make the completions available everywhere:

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.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-config

Synopsis

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

aliases: c

Description

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.

Sub-commands

Config supports the following sub-commands:

set

npm config set key value

Sets the config key to the value.

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

get

npm config get key

Echo the config value to stdout.

list

npm config list

Show all the config settings. Use -l to also show defaults. Use --json to show the settings in json format.

delete

npm config delete key

Deletes the key from all configuration files.

edit

npm config edit

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-dedupe

Synopsis

npm dedupe
npm ddp

aliases: find-dupes, ddp

Description

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 [email protected]
|   `-- [email protected]
`-- d <-- depends on [email protected]~1.0.9
    `-- [email protected]

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

a
+-- b
+-- d
`-- [email protected]

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.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-deprecate

Synopsis

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

Description

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

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

npm deprecate [email protected]"< 0.2.3" "critical bug fixed in v0.2.3"

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

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-dist-tag

Synopsis

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

aliases: dist-tags

Description

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.

PURPOSE

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.

CAVEATS

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.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-docs

Synopsis

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

Description

This command tries to guess at the likely location of a package's documentation URL, and then tries to open it using the --browser config param. 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.

Configuration

browser

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

registry

The base URL of the npm package registry.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-doctor

Synopsis

npm doctor

Description

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

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

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

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

npm ping

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

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

npm -v

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

node -v

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

npm config get registry

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

which git

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

Permissions checks

Validate the checksums of cached packages

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-edit

Synopsis

npm edit <pkg>[@<version>]

Description

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.

Configuration

editor

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-explore

Synopsis

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

Description

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

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

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

npm explore some-dependency -- git pull origin master

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

Configuration

shell

The shell to run for the npm explore command.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-help

Synopsis

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

Description

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

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

Configuration

viewer

The program to use to view help content.

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-help-search

Synopsis

npm help-search <text>

Description

This command will search the npm markdown documentation files for the terms provided, and then list the results, sorted by relevance.

If only one result is found, then it will show that help topic.

If the argument to npm help is not a known help topic, then it will call help-search. It is rarely if ever necessary to call this command directly.

Configuration

long

If true, the "long" flag will cause help-search to output context around where the terms were found in the documentation.

If false, then help-search will just list out the help topics found.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-hook

Synopsis

npm hook ls [pkg]
npm hook add <entity> <url> <secret>
npm hook update <id> <url> [secret]
npm hook rm <id>

EXAMPLE

Add a hook to watch a package for changes:

$ npm hook add lodash https://example.com/ my-shared-secret

Add a hook to watch packages belonging to the user substack:

$ npm hook add ~substack https://example.com/ my-shared-secret

Add a hook to watch packages in the scope @npm

$ npm hook add @npm https://example.com/ my-shared-secret

List all your active hooks:

$ npm hook ls

List your active hooks for the lodash package:

$ npm hook ls lodash

Update an existing hook's url:

$ npm hook update id-deadbeef https://my-new-website.here/

Remove a hook:

$ npm hook rm id-deadbeef

Description

Allows you to manage npm hooks, including adding, removing, listing, and updating.

Hooks allow you to configure URL endpoints that will be notified whenever a change happens to any of the supported entity types. Three different types of entities can be watched by hooks: packages, owners, and scopes.

To create a package hook, simply reference the package name.

To create an owner hook, prefix the owner name with ~ (as in, ~youruser).

To create a scope hook, prefix the scope name with @ (as in, @yourscope).

The hook id used by update and rm are the IDs listed in npm hook ls for that particular hook.

The shared secret will be sent along to the URL endpoint so you can verify the request came from your own configured hook.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-init

Synopsis

npm init [--force|-f|--yes|-y|--scope]
npm init <@scope> (same as `npx <@scope>/create`)
npm init [<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`)

EXAMPLES

Create a new React-based project using create-react-app:

$ npm init react-app ./my-react-app

Create a new esm-compatible package using create-esm:

$ mkdir my-esm-lib && cd my-esm-lib
$ npm init esm --yes

Generate a plain old package.json using legacy init:

$ mkdir my-npm-pkg && cd my-npm-pkg
$ git init
$ npm init

Generate it without having it ask any questions:

$ npm init -y

Description

npm init <initializer> can be used to set up a new or existing npm package.

initializer in this case is an npm package named create-<initializer>, which will be installed by npx, and then have its main bin executed -- presumably creating or updating package.json and running any other initialization-related operations.

The init command is transformed to a corresponding npx operation as follows:

Any additional options will be passed directly to the command, so npm init foo --hello will map to npx create-foo --hello.

If the initializer is omitted (by just calling npm init), init will fall back to legacy init behavior. It will ask you a bunch of questions, and then write a package.json for you. It will attempt to make reasonable guesses based on existing fields, dependencies, and options selected. It is strictly additive, so it will keep any fields and values that were already set. You can also use -y/--yes to skip the questionnaire altogether. If you pass --scope, it will create a scoped package.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-install

Synopsis

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 <git-host>:<git-user>/<repo-name>
npm install <git repo url>
npm install <tarball file>
npm install <tarball url>
npm install <folder>

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

Description

This command installs a package, and any packages that it depends on. If the package has a package-lock or shrinkwrap file, the installation of dependencies will be driven by that, with an npm-shrinkwrap.json taking precedence if both files exist. See package-lock.json and 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 [email protected]">=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 --package-lock-only argument will only update the package-lock.json, instead of checking node_modules and downloading dependencies.

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

npm install sax --force

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

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

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

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

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

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

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

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

The --no-package-lock argument will prevent npm from creating a package-lock.json file. When running with package-lock's disabled npm will not automatically prune your node modules when installing.

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.

The --no-audit argument can be used to disable sending of audit reports to the configured registries. See npm-audit for details on what is sent.

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

ALGORITHM

To install a package, npm uses the following algorithm:

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,[email protected]}, C{[email protected]}, this algorithm produces:

A
+-- B
+-- C
   `-- [email protected]
+-- [email protected]

Because B's [email protected] will be installed in the top level, C now has to install [email protected] privately for itself. This algorithm is deterministic, but different trees may be produced if two dependencies are requested for installation in a different order.

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

Limitations of npm's Install Algorithm

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

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

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

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

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm install-ci-test -- Install a project with a clean slate and run tests

Synopsis

npm install-ci-test

alias: npm cit

Description

This command runs an npm ci followed immediately by an npm test.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

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

Synopsis

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]

Description

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-link

Synopsis

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

alias: npm ln

Description

Package linking is a two-step process.

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

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

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

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

When creating tarballs for npm publish, the linked packages are "snapshotted" to their current state by resolving the symbolic links.

This is handy for installing your own stuff, so that you can work on it and test it iteratively without having to continually rebuild.

For example:

cd ~/projects/node-redis    # go into the package directory
npm link                    # creates global link
cd ~/projects/node-bloggy   # go into some other package directory.
npm link redis              # link-install the package

Now, any changes to ~/projects/node-redis will be reflected in ~/projects/node-bloggy/node_modules/node-redis/. Note that the link should be to the package name, not the directory name for that package.

You may also shortcut the two steps in one. For example, to do the above use-case in a shorter way:

cd ~/projects/node-bloggy  # go into the dir of your main project
npm link ../node-redis     # link the dir of your dependency

The second line is the equivalent of doing:

(cd ../node-redis; npm link)
npm link node-redis

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

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

npm link @myorg/privatepackage

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-logout

Synopsis

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

Description

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.

Configuration

registry

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

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

scope

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

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

npm logout [email protected]

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-ls

Synopsis

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

aliases: list, la, ll

Description

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

Positional arguments are [email protected] 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:

[email protected]@[email protected] /path/to/npm
└─┬ [email protected]
  └── [email protected]

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

If a project specifies git urls for dependencies these are shown in parentheses after the [email protected] 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.

Configuration

json

Show information in JSON format.

long

Show extended information.

parseable

Show parseable output instead of tree view.

global

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

depth

Max display depth of the dependency tree.

prod / production

Display only the dependency tree for packages in dependencies.

dev / development

Display only the dependency tree for packages in devDependencies.

only

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

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

link

Display only dependencies which are linked

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm

Synopsis

npm <command> [args]

VERSION

@[email protected]

Description

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

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

Run npm help to get a list of available commands.

INTRODUCTION

You probably got npm because you want to install stuff.

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

DEPENDENCIES

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

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

DIRECTORIES

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.

DEVELOPER USAGE

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

Configuration

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

See npm-config for much much more information.

CONTRIBUTIONS

Patches welcome!

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

If you would like to contribute, but don't know what to work on, read the contributing guidelines and check the issues list.

BUGS

When you find issues, please report them:

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

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

AUTHOR

Isaac Z. Schlueter :: isaacs :: @izs :: [email protected]

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-outdated

Synopsis

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

Description

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

In the output:

An example

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

Configuration

json

Show information in JSON format.

long

Show extended information.

parseable

Show parseable output instead of tree view.

global

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

depth

Max depth for checking dependency tree.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-owner

Synopsis

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

aliases: author

Description

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.

If you have two-factor authentication enabled with auth-and-writes then you'll need to include an otp on the command line when changing ownership with --otp.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-pack

Synopsis

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

Description

For anything that's installable (that is, a package folder, tarball, tarball url, [email protected], [email protected], 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.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-ping

Synopsis

npm ping [--registry <registry>]

Description

Ping the configured or given npm registry and verify authentication. If it works it will output something like:

Ping success: {*Details about registry*}

otherwise you will get:

Ping error: {*Detail about error}

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-prefix

Synopsis

npm prefix [-g]

Description

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.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-profile

Synopsis

npm profile get [--json|--parseable] [<property>]
npm profile set [--json|--parseable] <property> <value>
npm profile set password
npm profile enable-2fa [auth-and-writes|auth-only]
npm profile disable-2fa

Description

Change your profile information on the registry. This not be available if you're using a non-npmjs registry.

+-----------------+---------------------------+
| name            | example                   |
+-----------------+---------------------------+
| email           | [email protected] (verified) |
+-----------------+---------------------------+
| two factor auth | auth-and-writes           |
+-----------------+---------------------------+
| fullname        | Example User              |
+-----------------+---------------------------+
| homepage        |                           |
+-----------------+---------------------------+
| freenode        |                           |
+-----------------+---------------------------+
| twitter         |                           |
+-----------------+---------------------------+
| github          |                           |
+-----------------+---------------------------+
| created         | 2015-02-26T01:38:35.892Z  |
+-----------------+---------------------------+
| updated         | 2017-10-02T21:29:45.922Z  |
+-----------------+---------------------------+

DETAILS

All of the npm profile subcommands accept --json and --parseable and will tailor their output based on those. Some of these commands may not be available on non npmjs.com registries.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-prune

Synopsis

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

Description

This command removes "extraneous" packages. If a package name is provided, then only packages matching one of the supplied names are removed.

Extraneous packages are packages that are not listed on the parent package's dependencies list.

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 --no-production will negate NODE_ENV being set to production.

If the --dry-run flag is used then no changes will actually be made.

If the --json flag is used then the changes npm prune made (or would have made with --dry-run) are printed as a JSON object.

In normal operation with package-locks enabled, extraneous modules are pruned automatically when modules are installed and you'll only need this command with the --production flag.

If you've disabled package-locks then extraneous modules will not be removed and it's up to you to run npm prune from time-to-time to remove them.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-publish

Synopsis

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

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

Description

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.

As of [email protected], both a sha1sum and an integrity field with a sha512sum of the tarball will be submitted to the registry during publication. Subsequent installs will use the strongest supported algorithm to verify downloads.

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-rebuild

Synopsis

npm rebuild [[<@scope>/<name>]...]

alias: npm rb

Description

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-repo

Synopsis

npm repo [<pkg>]

Description

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.

Configuration

browser

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-restart

Synopsis

npm restart [-- <args>]

Description

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

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-root

Synopsis

npm root [-g]

Description

Print the effective node_modules folder to standard out.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-run-script

Synopsis

npm run-script <command> [--silent] [-- <args>...]

alias: npm run

Description

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 [email protected], 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.

The actual shell your script is run within is platform dependent. By default, on Unix-like systems it is the /bin/sh command, on Windows it is the cmd.exe. The actual shell referred to by /bin/sh also depends on the system. As of [email protected] you can customize the shell with the script-shell configuration.

Scripts are run from the root of the module, regardless of what your current working directory is when you call npm run. If you want your script to use different behavior based on what subdirectory you're in, you can use the INIT_CWD environment variable, which holds the full path you were in when you ran npm run.

npm run sets the NODE environment variable to the node executable with which npm is executed. Also, if the --scripts-prepend-node-path is passed, the directory within which node resides is added to the PATH. If --scripts-prepend-node-path=auto is passed (which has been the default in npm v3), this is only performed when that node executable is not found in the PATH.

If you try to run a script without having a node_modules directory and it fails, you will be given a warning to run npm install, just in case you've forgotten.

You can use the --silent flag to prevent showing npm ERR! output on error.

You can use the --if-present flag to avoid exiting with a non-zero exit code when the script is undefined. This lets you run potentially undefined scripts without breaking the execution chain.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-search

Synopsis

npm search [-l|--long] [--json] [--parseable] [--no-description] [search terms ...]

aliases: s, se, find

Description

Search the registry for packages matching the search terms. npm search performs a linear, incremental, lexically-ordered search through package metadata for all files in the registry. If color is enabled, it will further highlight the matches in the results.

Additionally, using the --searchopts and --searchexclude options paired with more search terms will respectively include and exclude further patterns. The main difference between --searchopts and the standard search terms is that the former does not highlight results in the output and can be used for more fine-grained filtering. Additionally, both of these can be added to .npmrc for default search filtering behavior.

Search also allows targeting of maintainers in search results, by prefixing their npm username with =.

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

A Note on caching

Configuration

description

Used as --no-description, disables search matching in package descriptions and suppresses display of that field in results.

json

Output search results as a JSON array.

parseable

Output search results as lines with tab-separated columns.

long

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.

searchopts

Space-separated options that are always passed to search.

searchexclude

Space-separated options that limit the results from search.

searchstaleness

The age of the cache, in seconds, before another registry request is made.

registry

Search the specified registry for modules. If you have configured npm to point to a different default registry, such as your internal private module repository, npm search will default to that registry when searching. Pass a different registry url such as the default above in order to override this setting.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-shrinkwrap

Synopsis

npm shrinkwrap

Description

This command repurposes package-lock.json into a publishable npm-shrinkwrap.json or simply creates a new one. The file created and updated by this command will then take precedence over any other existing or future package-lock.json files. For a detailed explanation of the design and purpose of package locks in npm, see npm-package-locks.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-star

Synopsis

npm star [<pkg>...]
npm unstar [<pkg>...]

Description

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-stars

Synopsis

npm stars [<user>]

Description

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.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-start

Synopsis

npm start [-- <args>]

Description

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 [email protected], you can use custom arguments when executing scripts. Refer to npm-run-script for more details.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-stop

Synopsis

npm stop [-- <args>]

Description

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-team

Synopsis

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>

Description

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.

DETAILS

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.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-test

Synopsis

  npm test [-- <args>]

  aliases: t, tst

Description

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

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-token

Synopsis

npm token list [--json|--parseable]
npm token create [--read-only] [--cidr=1.1.1.1/24,2.2.2.2/16]
npm token revoke <id|token>

Description

This list you list, create and revoke authentication tokens.

+--------+---------+------------+----------+----------------+
| id     | token   | created    | read-only | CIDR whitelist |
+--------+---------+------------+----------+----------------+
| 7f3134 | 1fa9ba… | 2017-10-02 | yes      |                |
+--------+---------+------------+----------+----------------+
| c03241 | af7aef… | 2017-10-02 | no       | 192.168.0.1/24 |
+--------+---------+------------+----------+----------------+
| e0cf92 | 3a436a… | 2017-10-02 | no       |                |
+--------+---------+------------+----------+----------------+
| 63eb9d | 74ef35… | 2017-09-28 | no       |                |
+--------+---------+------------+----------+----------------+
| 2daaa8 | cbad5f… | 2017-09-26 | no       |                |
+--------+---------+------------+----------+----------------+
| 68c2fe | 127e51… | 2017-09-23 | no       |                |
+--------+---------+------------+----------+----------------+
| 6334e1 | 1dadd1… | 2017-09-23 | no       |                |
+--------+---------+------------+----------+----------------+
+----------------+--------------------------------------+
| token          | a73c9572-f1b9-8983-983d-ba3ac3cc913d |
+----------------+--------------------------------------+
| cidr_whitelist |                                      |
+----------------+--------------------------------------+
| readonly       | false                                |
+----------------+--------------------------------------+
| created        | 2017-10-02T07:52:24.838Z             |
+----------------+--------------------------------------+

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-uninstall

Synopsis

npm uninstall [<@scope>/]<pkg>[@<version>]... [-S|--save|-D|--save-dev|-O|--save-optional|--no-save]

aliases: remove, rm, r, un, unlink

Description

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
npm uninstall lodash --no-save

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-unpublish

Synopsis

npm unpublish [<@scope>/]<pkg>[@<version>]

WARNING

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.

Description

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

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

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.

With the default registry (registry.npmjs.org), unpublish is only allowed with versions published in the last 24 hours. If you are trying to unpublish a version published longer ago than that, contact [email protected].

The scope is optional and follows the usual rules for npm-scope.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-update

Synopsis

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

aliases: up, upgrade

Description

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 [email protected], the npm update will only inspect top-level packages. Prior versions of npm would also recursively inspect all dependencies. To get the old behavior, use npm --depth 9999 update.

As of [email protected], the npm update will change package.json to save the new version as the minimum required dependency. To get the old behavior, use npm update --no-save.

EXAMPLES

IMPORTANT VERSION NOTE: these examples assume [email protected] 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"
  ]
}

Caret Dependencies

If app's package.json contains:

"dependencies": {
  "dep1": "^1.1.1"
}

Then npm update will install [email protected], because 1.2.2 is latest and 1.2.2 satisfies ^1.1.1.

Tilde Dependencies

However, if app's package.json contains:

"dependencies": {
  "dep1": "~1.1.1"
}

In this case, running npm update will install [email protected]. 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.

Caret Dependencies below 1.0.0

Suppose app has a caret dependency on a version below 1.0.0, for example:

"dependencies": {
  "dep1": "^0.2.0"
}

npm update will install [email protected], 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 [email protected], because that is the highest-sorting version that satisfies ^0.4.0 (>= 0.4.0 <0.5.0)

Updating Globally-Installed Packages

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.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-version

Synopsis

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

Description

Run this in a package directory to bump the version and write the new data back to package.json, package-lock.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/) <[email protected]>"
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.

Configuration

allow-same-version

Prevents throwing an error when npm version is used to set the new version to the same value as the current version.

git-tag-version

Commit and tag the version change.

commit-hooks

Run git commit hooks when committing the version change.

sign-git-tag

Pass the -s flag to git to sign the tag.

Note that you must have a default GPG key set up in your git config for this to work properly.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-view

Synopsis

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

aliases: info, show, v

Description

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

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

npm view connect

The default version is "latest" if unspecified.

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

npm view [email protected] 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 [email protected]$(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 [email protected]'>0.5.4' dependencies.jsdom

To show the connect package version history, you can do this:

npm view connect versions

OUTPUT

If only a single string field for a single version is output, then it will not be colorized or quoted, so as to enable piping the output to another command. If the 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.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-whoami

Synopsis

npm whoami [--registry <registry>]

Description

Print the username config to standard output.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-folders

Description

npm puts various things on your computer. That's its job.

This document will tell you what it puts where.

tl;dr

prefix Configuration

The prefix config defaults to the location where node is installed. On most systems, this is /usr/local. On Windows, it's %AppData%\npm. On Unix systems, it's one level up, since node is typically installed at {prefix}/bin/node rather than {prefix}/node.exe.

When the global flag is set, npm installs things into this prefix. When it is not set, it uses the root of the current package, or the current working directory if not in a package already.

Node Modules

Packages are dropped into the node_modules folder under the prefix. When installing locally, this means that you can require("packagename") to load its main module, or require("packagename/lib/path/to/sub/module") to load other modules.

Global installs on Unix systems go to {prefix}/lib/node_modules. Global installs on Windows go to {prefix}/node_modules (that is, no lib folder.)

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.

Executables

When in global mode, executables are linked into {prefix}/bin on Unix, or directly into {prefix} on Windows.

When in local mode, executables are linked into ./node_modules/.bin so that they can be made available to scripts run through npm. (For example, so that a test runner will be in the path when you run npm test.)

Man Pages

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

When in local mode, man pages are not installed.

Man pages are not installed on Windows systems.

Cache

See npm-cache. Cache files are stored in ~/.npm on Posix, or %AppData%/npm-cache on Windows.

This is controlled by the cache configuration param.

Temp Files

Temporary files are stored by default in the folder specified by the tmp config, which defaults to the TMPDIR, TMP, or TEMP environment variables, or /tmp on Unix and c:\windows\temp on Windows.

Temp files are given a unique folder under this root for each run of the program, and are deleted upon successful exit.

More Information

When installing locally, npm first tries to find an appropriate prefix folder. This is so that npm install [email protected] 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 [email protected], then the package is loaded into the cache, and then unpacked into ./node_modules/foo. Then, any of foo's dependencies are similarly unpacked into ./node_modules/foo/node_modules/....

Any bin files are symlinked to ./node_modules/.bin/, so that they may be found by npm scripts when necessary.

Global Installation

If the global configuration is set to true, then npm will install packages "globally".

For global installation, packages are installed roughly the same way, but using the folders described above.

Cycles, Conflicts, and Folder Parsimony

Cycles are handled using the property of node's module system that it walks up the directories looking for node_modules folders. So, at every stage, if a package is already installed in an ancestor node_modules folder, then it is not installed at the current location.

Consider the case above, where foo -> bar -> baz. Imagine if, in addition to that, baz depended on bar, so you'd have: foo -> bar -> baz -> bar -> baz .... However, since the folder structure is: foo/node_modules/bar/node_modules/baz, there's no need to put another copy of bar into .../baz/node_modules, since when it calls require("bar"), it will get the copy that is installed in foo/node_modules/bar.

This shortcut is only used if the exact same version would be installed in multiple nested node_modules folders. It is still possible to have a/node_modules/b/node_modules/a if the two "a" packages are different versions. However, without repeating the exact same package multiple times, an infinite regress will always be prevented.

Another optimization can be made by installing dependencies at the highest level possible, below the localized "target" folder.

Example

Consider this dependency graph:

foo
+-- [email protected]
+-- [email protected]
|   +-- [email protected] (latest=1.3.7)
|   +-- [email protected]
|   |   `-- [email protected]
|   |       `-- [email protected] (cycle)
|   `-- [email protected]*
`-- [email protected]
    `-- [email protected]
        `-- 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 [email protected] and [email protected], 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 [email protected], 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 [email protected], it cannot re-use the [email protected] installed in the parent node_modules folder [D], and must install its own copy [C].

Underneath bar, the baz -> quux -> bar dependency creates a cycle. However, because bar is already in quux's ancestry [B], it does not unpack another copy of bar into that folder.

Underneath foo -> baz [D], quux's [E] folder tree is empty, because its dependency on bar is satisfied by the parent folder copy installed at [B].

For a graphical breakdown of what is installed where, use npm ls.

Publishing

Upon publishing, npm will look in the node_modules folder. If any of the items there are not in the bundledDependencies array, then they will not be included in the package tarball.

This allows a package maintainer to install all of their dependencies (and dev dependencies) locally, but only re-publish those items that cannot be found elsewhere. See package.json for more information.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npmrc

Description

npm gets its config settings from the command line, environment variables, and npmrc files.

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

For a list of available configuration options, see npm-config.

FILES

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"

Comments

Lines in .npmrc files are interpreted as comments when they begin with a ; or # character. .npmrc files are parsed by npm/ini, which specifies this comment syntax.

For example:

# last modified: 01 Jan 2016
; Set a new registry for a scoped package
@myscope:registry=https://mycustomregistry.example.org

Per-project config file

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.

Per-user config file

$HOME/.npmrc (or the userconfig param, if set in the environment or on the command line)

Global config file

$PREFIX/etc/npmrc (or the globalconfig param, if set above): This file is an ini-file formatted list of key = value parameters. Environment variables can be replaced as above.

Built-in config file

path/to/npm/itself/npmrc

This is an unchangeable "builtin" configuration file that npm keeps consistent across updates. Set fields in here using the ./configure script that comes with npm. This is primarily for distribution maintainers to override default configs in a standard and consistent manner.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

package-lock.json

Description

package-lock.json is automatically generated for any operations where npm modifies either the node_modules tree, or package.json. It describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermediate dependency updates.

This file is intended to be committed into source repositories, and serves various purposes:

One key detail about package-lock.json is that it cannot be published, and it will be ignored if found in any place other than the toplevel package. It shares a format with npm-shrinkwrap.json, which is essentially the same file, but allows publication. This is not recommended unless deploying a CLI tool or otherwise using the publication process for producing production packages.

If both package-lock.json and npm-shrinkwrap.json are present in the root of a package, package-lock.json will be completely ignored.

FILE FORMAT

name

The name of the package this is a package-lock for. This must match what's in package.json.

version

The version of the package this is a package-lock for. This must match what's in package.json.

lockfileVersion

An integer version, starting at 1 with the version number of this document whose semantics were used when generating this package-lock.json.

packageIntegrity

This is a subresource integrity value created from the package.json. No preprocessing of the package.json should be done. Subresource integrity strings can be produced by modules like ssri.

preserveSymlinks

Indicates that the install was done with the environment variable NODE_PRESERVE_SYMLINKS enabled. The installer should insist that the value of this property match that environment variable.

dependencies

A mapping of package name to dependency object. Dependency objects have the following properties:

version

This is a specifier that uniquely identifies this package and should be usable in fetching a new copy of it.

integrity

This is a Standard Subresource Integrity for this resource.

resolved

bundled

If true, this is the bundled dependency and will be installed by the parent module. When installing, this module will be extracted from the parent module during the extract phase, not installed as a separate dependency.

dev

If true then this dependency is either a development dependency ONLY of the top level module or a transitive dependency of one. This is false for dependencies that are both a development dependency of the top level and a transitive dependency of a non-development dependency of the top level.

optional

If true then this dependency is either an optional dependency ONLY of the top level module or a transitive dependency of one. This is false for dependencies that are both an optional dependency of the top level and a transitive dependency of a non-optional dependency of the top level.

All optional dependencies should be included even if they're uninstallable on the current platform.

requires

This is a mapping of module name to version. This is a list of everything this module requires, regardless of where it will be installed. The version should match via normal matching rules a dependency either in our dependencies or in a level higher than us.

dependencies

The dependencies of this dependency, exactly as at the top level.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-package-locks

Description

Conceptually, the "input" to npm-install is a package.json, while its "output" is a fully-formed node_modules tree: a representation of the dependencies you declared. In an ideal world, npm would work like a pure function: the same package.json should produce the exact same node_modules tree, any time. In some cases, this is indeed true. But in many others, npm is unable to do this. There are multiple reasons for this:

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:

[email protected]
`-- [email protected]
    `-- [email protected]

However, if [email protected] is published, then a fresh npm install A will install:

[email protected]
`-- [email protected]
    `-- [email protected]

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 [email protected] 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.

To prevent this potential issue, npm uses package-lock.json or, if present, npm-shrinkwrap.json. These files are called package locks, or lockfiles.

Whenever you run npm install, npm generates or updates your package lock, which will look something like this:

{
  "name": "A",
  "version": "0.1.0",
  ...metadata fields...
  "dependencies": {
    "B": {
      "version": "0.0.1",
      "resolved": "https://registry.npmjs.org/B/-/B-0.0.1.tgz",
      "integrity": "sha512-DeAdb33F+"
      "dependencies": {
        "C": {
          "version": "git://github.com/org/C.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
        }
      }
    }
  }
}

This file describes an exact, and more importantly reproducible node_modules tree. Once it's present, any future installation will base its work off this file, instead of recalculating dependency versions off package.json.

The presence of a package lock changes the installation behavior such that:

  1. The module tree described by the package lock is reproduced. This means reproducing the structure described in the file, using the specific files referenced in "resolved" if available, falling back to normal package resolution using "version" if one isn't.

  2. The tree is walked and any missing dependencies are installed in the usual fashion.

If preshrinkwrap, shrinkwrap or postshrinkwrap are in the scripts property of the package.json, they will be executed in order. preshrinkwrap and shrinkwrap are executed before the shrinkwrap, postshrinkwrap is executed afterwards. These scripts run for both package-lock.json and npm-shrinkwrap.json. For example to run some postprocessing on the generated file:

"scripts": {
  "postshrinkwrap": "json -I -e \"this.myMetadata = $MY_APP_METADATA\""
}

Using locked packages

Using a locked package is no different than using any package without a package lock: any commands that update node_modules and/or package.json's dependencies will automatically sync the existing lockfile. This includes npm install, npm rm, npm update, etc. To prevent this update from happening, you can use the --no-save option to prevent saving altogether, or --no-shrinkwrap to allow package.json to be updated while leaving package-lock.json or npm-shrinkwrap.json intact.

It is highly recommended you commit the generated package lock to source control: this will allow anyone else on your team, your deployments, your CI/continuous integration, and anyone else who runs npm install in your package source to get the exact same dependency tree that you were developing on. Additionally, the diffs from these changes are human-readable and will inform you of any changes npm has made to your node_modules, so you can notice if any transitive dependencies were updated, hoisted, etc.

Resolving lockfile conflicts

Occasionally, two separate npm install will create package locks that cause merge conflicts in source control systems. As of [email protected], these conflicts can be resolved by manually fixing any package.json conflicts, and then running npm install [--package-lock-only] again. npm will automatically resolve any conflicts for you and write a merged package lock that includes all the dependencies from both branches in a reasonable tree. If --package-lock-only is provided, it will do this without also modifying your local node_modules/.

To make this process seamless on git, consider installing npm-merge-driver, which will teach git how to do this itself without any user interaction. In short: $ npx npm-merge-driver install -g will let you do this, and even works with pre-[email protected] versions of npm 5, albeit a bit more noisily. Note that if package.json itself conflicts, you will have to resolve that by hand and run npm install manually, even with the merge driver.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

package.json

Description

This document is all you need to know about what's required in your package.json file. It must be actual JSON, not just a JavaScript object literal.

A lot of the behavior described in this document is affected by the config settings described in npm-config.

name

If you plan to publish your package, the most important things in your package.json are the name and version fields as they will be required. 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. If you don't plan to publish your package, the name and version fields are optional.

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.

version

If you plan to publish your package, the most important things in your package.json are the name and version fields as they will be required. 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. If you don't plan to publish your package, the name and version fields are optional.

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.

description

Put a description in it. It's a string. This helps people discover your package, as it's listed in npm search.

keywords

Put keywords in it. It's an array of strings. This helps people discover your package as it's listed in npm search.

homepage

The url to the project homepage.

Example:

"homepage": "https://github.com/owner/project#readme"

bugs

The url to your project's issue tracker and / or the email address to which issues should be reported. These are helpful for people who encounter issues with your package.

It should look like this:

{ "url" : "https://github.com/owner/project/issues"
, "email" : "[email protected]"
}

You can specify either one or both values. If you want to provide only a url, you can specify the value for "bugs" as a simple string instead of an object.

If a url is provided, it will be used by the npm bugs command.

license

You should specify a license for your package so that people know how they are permitted to use it, and any restrictions you're placing on it.

If you're using a common license such as BSD-2-Clause or MIT, add a current SPDX license identifier for the license you're using, like this:

{ "license" : "BSD-3-Clause" }

You can check the full list of SPDX license IDs. Ideally you should pick one that is OSI approved.

If your package is licensed under multiple common licenses, use an SPDX license expression syntax version 2.0 string, like this:

{ "license" : "(ISC OR GPL-3.0)" }

If you are using a license that hasn't been assigned an SPDX identifier, or if you are using a custom license, use a string value like this one:

{ "license" : "SEE LICENSE IN <filename>" }

Then include a file named <filename> at the top level of the package.

Some old packages used license objects or a "licenses" property containing an array of license objects:

// Not valid metadata
{ "license" :
  { "type" : "ISC"
  , "url" : "https://opensource.org/licenses/ISC"
  }
}

// Not valid metadata
{ "licenses" :
  [
    { "type": "MIT"
    , "url": "https://www.opensource.org/licenses/mit-license.php"
    }
  , { "type": "Apache-2.0"
    , "url": "https://opensource.org/licenses/apache2.0.php"
    }
  ]
}

Those styles are now deprecated. Instead, use SPDX expressions, like this:

{ "license": "ISC" }

{ "license": "(MIT OR Apache-2.0)" }

Finally, if you do not wish to grant others the right to use a private or unpublished package under any terms:

{ "license": "UNLICENSED" }

Consider also setting "private": true to prevent accidental publication.

people fields: author, contributors

The "author" is one person. "contributors" is an array of people. A "person" is an object with a "name" field and optionally "url" and "email", like this:

{ "name" : "Barney Rubble"
, "email" : "[email protected]"
, "url" : "http://barnyrubble.tumblr.com/"
}

Or you can shorten that all into a single string, and npm will parse it for you:

"Barney Rubble <[email protected]> (http://barnyrubble.tumblr.com/)"

Both email and url are optional either way.

npm also sets a top-level "maintainers" field with your npm user info.

files

The optional files field is an array of file patterns that describes the entries to be included when your package is installed as a dependency. File patterns follow a similar syntax to .gitignore, but reversed: including a file, directory, or glob pattern (*, **/*, and such) will make it so that file is included in the tarball when it's packed. Omitting the field will make it default to ["*"], which means it will include all files.

Some special files and directories are also included or excluded regardless of whether they exist in the files array (see below).

You can also provide a .npmignore file in the root of your package or in subdirectories, which will keep files from being included. At the root of your package it will not override the "files" field, but in subdirectories it will. The .npmignore file works just like a .gitignore. If there is a .gitignore file, and .npmignore is missing, .gitignore's contents will be used instead.

Files included with the "package.json#files" field cannot be excluded through .npmignore or .gitignore.

Certain files are always included, regardless of settings:

README, CHANGES, LICENSE & NOTICE can have any case and extension.

Conversely, some files are always ignored:

main

The main field is a module ID that is the primary entry point to your program. That is, if your package is named foo, and a user installs it, and then does require("foo"), then your main module's exports object will be returned.

This should be a module ID relative to the root of your package folder.

For most modules, it makes the most sense to have a main script and often not much else.

browser

If your module is meant to be used client-side the browser field should be used instead of the main field. This is helpful to hint users that it might rely on primitives that aren't available in Node.js modules. (e.g. window)

bin

A lot of packages have one or more executable files that they'd like to install into the PATH. npm makes this pretty easy (in fact, it uses this feature to install the "npm" executable.)

To use this, supply a bin field in your package.json which is a map of command name to local file name. On install, npm will symlink that file into prefix/bin for global installs, or ./node_modules/.bin/ for local installs.

For example, myapp could have this:

{ "bin" : { "myapp" : "./cli.js" } }

So, when you install myapp, it'll create a symlink from the cli.js script to /usr/local/bin/myapp.

If you have a single executable, and its name should be the name of the package, then you can just supply it as a string. For example:

{ "name": "my-program"
, "version": "1.2.5"
, "bin": "./path/to/program" }

would be the same as this:

{ "name": "my-program"
, "version": "1.2.5"
, "bin" : { "my-program" : "./path/to/program" } }

Please make sure that your file(s) referenced in bin starts with #!/usr/bin/env node, otherwise the scripts are started without the node executable!

man

Specify either a single file or an array of filenames to put in place for the man program to find.

If only a single file is provided, then it's installed such that it is the result from man <pkgname>, regardless of its actual filename. For example:

{ "name" : "foo"
, "version" : "1.2.3"
, "description" : "A packaged foo fooer for fooing foos"
, "main" : "foo.js"
, "man" : "./man/doc.1"
}

would link the ./man/doc.1 file in such that it is the target for man foo

If the filename doesn't start with the package name, then it's prefixed. So, this:

{ "name" : "foo"
, "version" : "1.2.3"
, "description" : "A packaged foo fooer for fooing foos"
, "main" : "foo.js"
, "man" : [ "./man/foo.1", "./man/bar.1" ]
}

will create files to do man foo and man foo-bar.

Man files must end with a number, and optionally a .gz suffix if they are compressed. The number dictates which man section the file is installed into.

{ "name" : "foo"
, "version" : "1.2.3"
, "description" : "A packaged foo fooer for fooing foos"
, "main" : "foo.js"
, "man" : [ "./man/foo.1", "./man/foo.2" ]
}

will create entries for man foo and man 2 foo

directories

The CommonJS Packages spec details a few ways that you can indicate the structure of your package using a directories 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.

directories.lib

Tell people where the bulk of your library is. Nothing special is done with the lib folder in any way, but it's useful meta info.

directories.bin

If you specify a bin directory 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.

directories.man

A folder that is full of man pages. Sugar to generate a "man" array by walking the folder.

directories.doc

Put markdown files in here. Eventually, these will be displayed nicely, maybe, someday.

directories.example

Put example scripts in here. Someday, it might be exposed in some clever way.

directories.test

Put your tests in here. It is currently not exposed, but it might be in the future.

repository

Specify the place where your code lives. This is helpful for people who want to contribute. If the git repo is on GitHub, then the npm docs command will be able to find you.

Do it like this:

"repository" :
  { "type" : "git"
  , "url" : "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": "github:user/repo"

"repository": "gist:11081aaa281"

"repository": "bitbucket:user/repo"

"repository": "gitlab:user/repo"

scripts

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.

config

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

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

URLs as Dependencies

You may specify a tarball URL in place of a version range.

This tarball will be downloaded and installed locally to your package at install time.

Git URLs as Dependencies

Git urls are of the form:

<protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]

<protocol> is one of git, git+ssh, git+http, git+https, or git+file.

If #<commit-ish> is provided, it will be used to clone exactly that commit. If the commit-ish has the format #semver:<semver>, <semver> can be any valid semver range or exact version, and npm will look for any tags or refs matching that range in the remote repository, much as it would for a registry dependency. If neither #<commit-ish> or #semver:<semver> is specified, then master is used.

Examples:

git+ssh://[email protected]:npm/npm.git#v1.0.27
git+ssh://[email protected]:npm/npm#semver:^5.0
git+https://[email protected]/npm/npm.git
git://github.com/npm/npm.git#v1.0.27

GitHub URLs

As of version 1.1.65, you can refer to GitHub urls as just "foo": "user/foo-project". Just as with git URLs, a commit-ish suffix can be included. For example:

{
  "name": "foo",
  "version": "0.0.0",
  "dependencies": {
    "express": "expressjs/express",
    "mocha": "mochajs/mocha#4727d357ea",
    "module": "user/repo#feature\/branch"
  }
}

Local Paths

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.

devDependencies

If someone is planning on downloading and using your module in their program, then they probably don't want or need to download and build the external test or documentation framework that you use.

In this case, it's best to map these additional items in a devDependencies object.

These things will be installed when doing npm link or npm install from the root of a package, and can be managed like any other npm configuration param. See npm-config for more on the topic.

For build steps that are not platform-specific, such as compiling CoffeeScript or other languages to JavaScript, use the prepare script to do this, and make the required package a devDependency.

For example:

{ "name": "ethopia-waza",
  "description": "a delightfully fruity coffee varietal",
  "version": "1.2.3",
  "devDependencies": {
    "coffee-script": "~1.6.3"
  },
  "scripts": {
    "prepare": "coffee -o lib/ -c src/waza.coffee"
  },
  "main": "lib/waza.js"
}

The prepare script will be run before publishing, so that users can consume the functionality without requiring them to compile it themselves. In dev mode (ie, locally running npm install), it'll run this script as well, so that you can test it easily.

peerDependencies

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:

├── [email protected]
└── [email protected]

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 ([email protected]), 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".

bundledDependencies

This defines an array of package names that will be bundled when publishing the package.

In cases where you need to preserve npm packages locally or have them available through a single file download, you can bundle the packages in a tarball file by specifying the package names in the bundledDependencies array and executing npm pack.

For example:

If we define a package.json like this:

{
  "name": "awesome-web-framework",
  "version": "1.0.0",
  "bundledDependencies": [
    "renderized", "super-streams"
  ]
}

we can obtain awesome-web-framework-1.0.0.tgz file by running npm pack. This file contains the dependencies renderized and super-streams which can be installed in a new project by executing npm install awesome-web-framework-1.0.0.tgz.

If this is spelled "bundleDependencies", then that is also honored.

optionalDependencies

If a dependency can be used, but you would like npm to proceed if it cannot be found or fails to install, then you may put it in the optionalDependencies 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.

engines

You can specify the version of node that your stuff works on:

{ "engines" : { "node" : ">=0.10.3 <0.12" } }

And, like with dependencies, if you don't specify the version (or if you specify "*" as the version), then any version of node will do.

If you specify an "engines" field, then npm will require that "node" be somewhere on that list. If "engines" is omitted, then npm will just assume that it works on node.

You can also use the "engines" field to specify which versions of npm are capable of properly installing your program. For example:

{ "engines" : { "npm" : "~1.0.20" } }

Unless the user has set the engine-strict config flag, this field is advisory only and will only produce warnings when your package is installed as a dependency.

engineStrict

This feature was removed in npm 3.0.0

Prior to npm 3.0.0, this feature was used to treat this package as if the user had set engine-strict. It is no longer used.

os

You can specify which operating systems your module will run on:

"os" : [ "darwin", "linux" ]

You can also blacklist instead of whitelist operating systems, just prepend the blacklisted os with a '!':

"os" : [ "!win32" ]

The host operating system is determined by process.platform

It is allowed to both blacklist, and whitelist, although there isn't any good reason to do this.

cpu

If your code only runs on certain cpu architectures, you can specify which ones.

"cpu" : [ "x64", "ia32" ]

Like the os option, you can also blacklist architectures:

"cpu" : [ "!arm", "!mips" ]

The host architecture is determined by process.arch

preferGlobal

DEPRECATED

This option used to trigger an npm warning, but it will no longer warn. It is purely there for informational purposes. It is now recommended that you install any binaries as local devDependencies wherever possible.

private

If you set "private": true in your package.json, then npm will refuse to publish it.

This is a way to prevent accidental publication of private repositories. If you would like to ensure that a given package is only ever published to a specific registry (for example, an internal registry), then use the publishConfig dictionary described below to override the registry config param at publish-time.

publishConfig

This is a set of config values that will be used at publish-time. It's especially handy if you want to set the tag, 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 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.

DEFAULT VALUES

npm will default some values based on package contents.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

npm-shrinkwrap.json

Description

npm-shrinkwrap.json is a file created by npm-shrinkwrap. It is identical to package-lock.json, with one major caveat: Unlike package-lock.json, npm-shrinkwrap.json may be included when publishing a package.

The recommended use-case for npm-shrinkwrap.json is applications deployed through the publishing process on the registry: for example, daemons and command-line tools intended as global installs or devDependencies. It's strongly discouraged for library authors to publish this file, since that would prevent end users from having control over transitive dependency updates.

Additionally, if both package-lock.json and npm-shrinkwrap.json are present in a package root, package-lock.json will be ignored in favor of this file.

For full details and description of the npm-shrinkwrap.json file format, refer to the manual page for package-lock.json.

See Also

Last modified October 26, 1985           Found a typo? Send a pull request!

Last modified February 17, 2018           Found a typo? Send a pull request!

Last modified February 17, 2018           Found a typo? Send a pull request!

Last modified February 17, 2018           Found a typo? Send a pull request!

Last modified February 17, 2018           Found a typo? Send a pull request!

Last modified February 17, 2018           Found a typo? Send a pull request!

Last modified February 17, 2018           Found a typo? Send a pull request!

npm Services

Getting started

Private packages

Troubleshooting

Using npm

CLI commands

Configuring npm

View All On One Page