# npm-upgrade

Interactive CLI utility to easily update outdated NPM dependencies with changelogs inspection support.

[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url]

## What is this for?

If you are tired of manually upgrading `package.json` every time your package dependencies are getting out of date then this utility is for you.

Take a look at this demo:

![npm-upgrade outdated packages](https://cloud.githubusercontent.com/assets/302213/11168821/08311b90-8bb2-11e5-9a71-5da73682ed44.gif)

## Installation

First, install [Node.js](https://nodejs.org) (at least `v10.19`).

Then install this utility as global npm-module:

```sh
npm i -g npm-upgrade
```

## Usage

This utility is supposed to be run in the root directory of your Node.js project (that contains `package.json`).
Run `npm-upgrade --help` to see all available top-level commands:

```
check [filter]          Check for outdated modules
ignore <command>        Manage ignored modules
changelog <moduleName>  Show changelog for a module
```

Run `npm-upgrade <command> --help` to see usage help for corresponding command.
`check` is the default command and can be omitted so running `npm-upgrade [filter]` is the same as `npm-upgrade check [filter]`.

### `check` command

It will find all your outdated deps and will ask to updated their versions in `package.json`, one by one.
For example, here is what you will see if you use outdated version of `@angular/common` module:

```
Update "@angular/common" in package.json from 2.4.8 to 2.4.10? (Use arrow keys)
❯ Yes
  No
  Show changelog
  Ignore
  Finish update process
```

- `Yes` will update `@angular/common` version in `package.json` to `2.4.10`, but not immediately (see explanation below)
- `No` will not update this module version.
- `Show changelog` will try to find changelog url for the current module and open it in default browser.
- `Ignore` will add this module to the ignored list (see details in [`Ignoring module`](#ignoring-module) section below).
- `Finish update process` will ...hm... finish update process and save all the changes to `package.json`.

A note on saving changes to `package.json`: when you choose `Yes` to update some module's version, `package.json` won't be immediately updated. It will be updated only after you will process all the outdated modules and confirm update **or** when you choose `Finish update process`. So if in the middle of the update process you've changed your mind just press `Ctrl+C` and `package.json` will remain untouched.

If you want to check only some deps, you can use `filter` argument:

```sh
# Will check only `babel-core` module:
npm-upgrade babel-core

# Will check all the deps with `babel` in the name:
npm-upgrade '*babel*'

# Note quotes around `filter`. They are necessary because without them bash may interpret `*` as wildcard character.

# Will check all the deps, excluding any with `babel` in the name:
npm-upgrade '!*babel*'

# You can combine including and excluding rules:
npm-upgrade '*babel* !babel-transform-* !babel-preset-*'
```

If you want to check only a group of deps use these options:

```
-p, --production   Check only "dependencies"
-d, --development  Check only "devDependencies"
-o, --optional     Check only "optionalDependencies"
```

If you want to check only for specific version updates, use the `-t` (`--target`) option:

```
-t, --target <value>  Specify the target version to upgrade to
```

Available values:

- `latest` (default) - Upgrade to whatever the package's "latest" dist-tag points to.
- `greatest` - Upgrade to the highest version number published, regardless of release date or tag. Includes prereleases.
- `minor` - Upgrade to the highest minor version without bumping the major version. (e.g., 1.0.0 → 1.9.0)
- `patch` - Upgrade to the highest patch version without bumping the minor or major versions. (e.g., 1.0.0 → 1.0.9)

Examples:

```sh
npm-upgrade                  # default behavior (latest)
npm-upgrade --target=patch   # only patches
npm-upgrade -t minor         # only minor versions
```

Alternatively, you can use the `-g` (`--global`) flag to upgrade your global packages. **Note** that this flag is mutually exclusive and `npm-upgrade` will only recognise the global flag if supplied with others. Also **Note** that this option will automatically attempt to upgrade your global packages using `npm install -g <package>@<new-version>`.

#### Ignoring module

Sometimes you just want to ignore newer versions of some dependency for some reason. For example, you use `jquery v2` because of the old IE support and don't want `npm-upgrade` to suggest you updating it to `v3`. Or you use `some-funky-module@6.6.5` and know that the new version `6.6.6` contains a bug that breaks your app.

You can handle these situations by ignoring such modules. You can do it in two ways: choosing `Ignore` during update process or using `npm ignore add` command.

You will asked two questions. First is a version range to ignore. It should be a valid [semver](http://semver.org/) version. Here are a few examples:

- `6.6.6` - will ignore only version `6.6.6`. When the next version after `6.6.6` will be published `npm-upgrade` will suggest to update it. Can be used in `some-funky-module` example above.
- `>2` - will ignore all versions starting from `3.0.0`. Can be used in `jquery v2` example above.
- `6.6.x || 6.7.x` - will ignore all `6.6.x` and `6.7.x` versions.
- `*` - will ignore all new versions.

And after that `npm-upgrade` will ask about the ignore reason. The answer is optional but is strongly recommended because it will help to explain your motivation to your сolleagues and to yourself after a few months.

All the data about ignored modules will be stored in `.npm-upgrade.json` file next to your project's `package.json`.

### `ignore` command

It will help you manage ignored modules. See [Ignoring module](#ignoring-module) section for more details.
It has the following subcommands:

```
npm-upgrade ignore <command>

Commands:
  add [module]        Add module to ignored list
  list                Show the list of ignored modules
  reset [modules...]  Reset ignored modules
```

- `add` - will add a module from your deps to ignored list. You can either provide module name as optional `module` argument or interactively select it from the list of project's deps.
- `list` - will show the list of currently ignored modules along with their ignored versions and reasons.
- `reset` - will remove modules from the ignored list. You can either provide module names as `modules` argument (separated by space) or interactively select them from the list of project's deps.

### `changelog` command

```
npm-upgrade changelog <moduleName>
```

Will try to find changelog url for provided module and open it in default browser.

## Troubleshooting

**Wrong changelog shown for _\<moduleName\>_ or not shown at all!**

Yes, It can happen sometimes. This is because there is no standardized way to specify changelog location for the module, so it tries to guess it, using these rules one by one:

1. Check `db/changelogUrls.json` from `master` branch on GitHub or the local copy if it's unreachable.
2. Check `changelog` field from module's `package.json`.
3. Parse module's `repository.url` field and if it's on GitHub or GitLab, try to request some common changelog files (`CHANGELOG.md`, `History.md` etc.) from main branch and if it fails, open `Releases` page.

So, if it guessed wrong it would be great if you could either [fill an issue](../../issues/new) about this or submit a PR which adds proper changelog URL to `db/changelogUrls.json`. There is a tool in the repository for you to make it as easy as possible:

```sh
./tools/addModuleChangelogUrlToDb.js <moduleName> <changelogUrl>
```

## License

[MIT](LICENSE)

[downloads-image]: https://img.shields.io/npm/dt/npm-upgrade.svg
[npm-url]: https://www.npmjs.com/package/npm-upgrade
[npm-image]: https://img.shields.io/npm/v/npm-upgrade.svg