Skip to content

CLI for a painless way to upgrade your package.json dependencies!

License

Notifications You must be signed in to change notification settings

xmatters/upgreat

Repository files navigation

upgreat

Maintainability Test Coverage Build Status

upgreat is a CLI for a painless way to upgrade your package dependencies!

upgreat helps you upgrade the dependencies of your project. Have it plan and execute upgrades for you, making sure they don't cause any issues. It will run tests (or builds), attempt an upgrade for a package, then run the tests/build again to verify.

upgreat is smart:

  • it will roll back failed upgrades: upgrading everything it can without breaking tests and builds
  • it knows about devDependencies: it will run builds instead of tests
  • it understands peerDependencies: it will attempt the least intrusive upgrades first, and warn you of missing ones
  • it supports yarn and npm

It can plan based on:

  • package type: dependencies|devDependencies
  • include regex
  • exclude regex

It can upgrade all dependencies:

  • with yarn or npm
  • using test and build scripts defined in your package.json

usage

You can use this package directly via npx, or install it globally (npm install @xmatters/upgreat -g).

upgreat [COMMAND]
# eg: upgreat help
# eg: npx @xmatters/upgreat help

COMMANDS

  help  # display help for upgreat
  plan  # create the upgrade plan for the package
  up    # execute the upgrade plan

1. upgreat plan

First, create an upgrade plan via the plan command. This will create a file .upgreat/plan.json with the details and order of upgrade for each package.

upgreat plan
# create the upgrade plan
# by default, plans upgrade of ALL dependencies

OPTIONS

-i, --include=include                           # include packages by regex
-p, --packageType=dependencies|devDependencies  # limit to a specific package type
-x, --exclude=exclude                           # exclude packages by regex

2. upgreat up

Then, execute the upgrade plan via the up command. This will read .upgreat/plan.json and start upgrading packages and testing/building.

upgreat up
# execute the upgrade plan

OPTIONS

-b, --buildScript=buildScriptName   # name of the npm script in package.json
                                    # used for building your app [default: build]

-t, --testScript=testScriptName     # name of the npm script in package.json
                                    # used for building your app [default: test]

--npm                               # use npm

You can pass -b or --buildScript to define which script in your package.json gets run after upgrading a devDependency. By default this is build so upgreat will use yarn build or npm run build.

Similarly, -t or --testScript defines the test script in package.json to run after upgrading a dependency. By default this is test so upgreat will use yarn test or npm run test.

You can customize both for your purposes: npx @xmatters/upgreat up --npm -b build:prod -t test:ci will use npm and use build:prod script for devDependencies and test:ci script for dependencies.

Sit back and watch it do it's thing. Any upgrades that cause failures will be rolled back. .upgreat/ directory will contain any dependencies that failed with stderr info in separate files.

usage example

Move to the folder of your package and create an upgrade plan

cd my-project
upgreat plan

# or

npx @xmatters/upgreat plan

then,

upgreat up

# or

# yarn:
npx @xmatters/upgreat up
# npm:
npx @xmatters/upgreat up --npm

If you were using npm, and your test script was named testTheProjectPls you would invoke it as:

upgreat up --npm -t testTheProjectPls

roadmap / todo

  • html upgrade report with changelogs

related

Greenkeeper, Dependabot and Renovate address similar problems, but either need tight GitHub integration or are not free. Do you need to make sure all your dependencies are up to date, or merge PRs all day for @babel/plugin-proposal-logical-assignment-operators 7.0.0 -> 7.0.2 from bots? If the former, give upgreat a try!