Created: 2013-09-24 01:18
Updated: 2019-02-25 21:46


Async NPM shell commands: install, test, etc.

NPM info

Build dependencies devDependencies

Codacy Badge semantic-release manpm next-update-travis badge renovate-app badge


var npmUtils = require('npm-utils');
  .then(function (semver) {
    console.log('NPM version %s', semver);


NPM command path

path() // returns immediately path to npm command


  name: string,
  version: string (optional),
  prefix: string (optional), // folder path prefix
  passThroughData: obj (optional),
  registry: string (optional) // registry url,
  flags: ['--save', '--verbose'] // list of command line flags to pass to NPM

returns a promise

Note: the name could be another folder or a tar archive; passed to npm install <name> unchanged, that can be any match. See npm help install.

Without name property, it just runs npm install in the current folder.


Clones Git repository for given NPM module and installs dependencies in the cloned folder.

  name: string, // NPM module name
  folder: string // destination new folder to create

Returns a promise


version() // returns a promise, resolved with NPM version string


test() // spawns npm test command
test('grunt test'); // spawns new command "grunt test"

The child test process will inherit output streams from the parent.


// returns a promise resolved with result of
// pass scope for specific registry
  .then(url => ...)


publish({ tag: '...'});
// the tag is optional


Loads package.json from a given folder

var pkg = npm.getPackage(folder);
console.log('%s version %s',, pkg.version);


Runs npm pack <folder name> command. Resolves with the name of the generated tarball file.

pack({ folder: 'path/to/folder' })

If folder is not provided, uses the current one


Please execute the npm login first!

    .then(canPublishNow, onError)

Updates local .npmrc (if found) or profile ~/.npmrc file that can be used by CI servers to publish to NPM. The file will have the following line added (only the actual registry url will be used)


Read the Deploying with npm private modules for details, see project ci-publish for example how this could be used to release from CI after successful tests.

Often the source of errors is that the environment does not have NPM_TOKEN set, or the .npmrc file already has the authToken entry for this registry. For example, when running locally

$ NPM_TOKEN=foo node src/set-auth-token.js
npmrc file already has auth token for registry
[Error: Auth token for registry exists //]

increment or set package version

Runs npm version [major | minor | patch | version] command.

  increment: 'major|minor|patch|semver version',
  noGit: true // default false = Git commit happens
// example
  increment: '2.0.1'

See npm help version.

Prune dependencies

// same as "npm prune"

Bin commands

Set auth token name

Often the CI needs an auth token for a registry to be able to install private modules. The CI should have NPM_TOKEN environment variable set, and the next command adds the following to the .npmrc or ~/.npmrc file


You can use it like this. From the CI build file (circle.yml, .travis.yml etc) first install this package, then call the command, and then install all modules (including the private ones)

npm i npm-utils
$(npm bin)/set-auth-token-var-name
npm i



Run the command with DEBUG=npm-utils environment variable set, this package uses debug

Small print

Author: Gleb Bahmutov @ 2013 @bahmutov

License: MIT - do anything with the code, but don't blame me if it does not work.

Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more