# npm-utils

> Async NPM shell commands

Latest version **2.0.3** (published 2018-03-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install npm-utils
pnpm add npm-utils
yarn add npm-utils
bun add npm-utils
```

Provides the command `set-auth-token-var-name`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.3 |
| Published | 2018-03-20 |
| First published | 2013-08-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >0.4.0 |
| Dependencies | 13 |
| Unpacked size | 29.4 KB |
| Known vulnerabilities | 0 (+3 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 10 |
| Author | Gleb Bahmutov |
| Maintainers | bahmutov |
| Keywords | async, command, npm, shell |

## Links

- npm: https://www.npmjs.com/package/npm-utils
- Repository: https://github.com/bahmutov/npm-utils
- Issues: https://github.com/bahmutov/npm-utils/issues
- npm.io page: https://npm.io/package/npm-utils

## Dependencies (13)

- [q](https://npm.io/package/q.md) 2.0.3
- [del](https://npm.io/package/del.md) 3.0.0
- [ggit](https://npm.io/package/ggit.md) 2.4.2
- [debug](https://npm.io/package/debug.md) 3.1.0
- [execa](https://npm.io/package/execa.md) 0.10.0
- [lazy-ass](https://npm.io/package/lazy-ass.md) 1.6.0
- [repo-url](https://npm.io/package/repo-url.md) 1.0.1
- [cross-spawn](https://npm.io/package/cross-spawn.md) 6.0.5
- [registry-url](https://npm.io/package/registry-url.md) 3.1.0
- [chdir-promise](https://npm.io/package/chdir-promise.md) 0.6.2
- [check-more-types](https://npm.io/package/check-more-types.md) 2.24.0
- [verbal-expressions](https://npm.io/package/verbal-expressions.md) 0.3.0
- [local-or-home-npmrc](https://npm.io/package/local-or-home-npmrc.md) 1.1.0

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 2.0.3 (latest) — 2018-03-20
- 2.0.2 — 2018-03-20
- 2.0.1 — 2018-03-15
- 2.0.0 — 2017-07-24
- 1.14.1 — 2017-07-11
- 1.14.0 — 2017-07-10
- 1.13.0 — 2017-07-10
- 1.12.0 — 2017-03-31
- 1.11.0 — 2016-12-06
- 1.10.1 — 2016-11-30
- 1.10.0 — 2016-11-01
- 1.9.0 — 2016-09-05
- 1.8.0 — 2016-08-17
- 1.7.1 — 2016-07-28
- 1.7.0 — 2016-07-27
- … 37 more at https://npm.io/package/npm-utils/versions

## README

# npm-utils

Async NPM shell commands: install, test, etc.

[![NPM info][nodei.co]][npm-url]

[![Build][npm-utils-ci-image]][npm-utils-ci-url]
[![dependencies][dependencies-image]][dependencies-url]
[![devDependencies][devDependencies-image]][devDependencies-url]

[![Codacy Badge][codacy-image]][codacy-url]
[![semantic-release][semantic-image] ][semantic-url]
[![manpm](https://img.shields.io/badge/manpm-%E2%9C%93-3399ff.svg)](https://github.com/bahmutov/manpm)
[![next-update-travis badge][badge]][readme]
[![renovate-app badge][renovate-badge]][renovate-app]

[renovate-badge]: https://img.shields.io/badge/renovate-app-blue.svg
[renovate-app]: https://renovateapp.com/

## Use

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

## API

### NPM command path

```js
path() // returns immediately path to npm command
```

### Install

```js
install({
  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.

### repoInstall

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

```js
repoInstall({
  name: string, // NPM module name
  folder: string // destination new folder to create
})
```

Returns a promise

### Version

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

### Test

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

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

### registryUrl

```js
registryUrl();
// returns a promise resolved with result of https://github.com/sindresorhus/registry-url
// pass scope for specific registry
registryUrl('@myCo')
  .then(url => ...)
```

### publish

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

### getPackage

Loads `package.json` from a given folder

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

### pack

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

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

If folder is not provided, uses the current one

### setAuthToken

Please execute the `npm login` first!

```js
setAuthToken()
    .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)

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

Read the [Deploying with npm private modules][deploying post] for details, see
project [ci-publish](https://github.com/bahmutov/ci-publish) for example how this could be
used to release from CI after successful tests.

[deploying post]: http://blog.npmjs.org/post/118393368555/deploying-with-npm-private-modules

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
    //registry.npmjs.org/:_authToken=
    [Error: Auth token for registry exists //registry.npmjs.org/:_authToken=]

### increment or set package version

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

```js
incrementVersion({
  increment: 'major|minor|patch|semver version',
  noGit: true // default false = Git commit happens
})
// example
incrementVersion({
  increment: '2.0.1'
})
```

See `npm help version`.

### Prune dependencies

```js
require('npm-utils').prune().catch(console.error);
// 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

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

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)

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

## Related

* [ggit](https://github.com/bahmutov/ggit) - Git utils

## Troubleshooting

Run the command with `DEBUG=npm-utils` environment variable set, this package
uses [debug](https://www.npmjs.com/package/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.

* [@bahmutov](https://twitter.com/bahmutov)
* [glebbahmutov.com](http://glebbahmutov.com)
* [blog](http://glebbahmutov.com/blog)

[nodei.co]: https://nodei.co/npm/npm-utils.svg?downloads=true
[npm-url]: https://npmjs.org/package/npm-utils
[npm-utils-ci-image]: https://secure.travis-ci.org/bahmutov/npm-utils.svg?branch=master
[npm-utils-ci-url]: https://travis-ci.org/bahmutov/npm-utils
[dependencies-image]: https://david-dm.org/bahmutov/npm-utils.svg
[dependencies-url]: https://david-dm.org/bahmutov/npm-utils
[devDependencies-image]: https://david-dm.org/bahmutov/npm-utils/dev-status.svg
[devDependencies-url]: https://david-dm.org/bahmutov/npm-utils#info=devDependencies
[codacy-image]: https://api.codacy.com/project/badge/grade/80f4a9c1aad545fa8aeb090d66a3a7d2
[codacy-url]: https://www.codacy.com/app/glebbahmutov_2600/npm-utils
[semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
[semantic-url]: https://github.com/semantic-release/semantic-release
[badge]: https://img.shields.io/badge/next--update--travis-%E2%9C%94%EF%B8%8F-green.svg
[readme]: https://github.com/bahmutov/next-update-travis#readme

---
_Source: https://npm.io/package/npm-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._