node package manager


Async NPM shell commands


Async NPM shell commands: install, test, etc.

var npmUtils = require('npm-utils');
  .then(function (semver) {
    console.log('NPM version %s', semver);
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 the ~/.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 //]

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.

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

Author: Gleb Bahmutov @ 2013 @bahmutov

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