Requires Node.js 22.12.0 or newer.
Running the tests with AVA requires Node 22.20+, Node 24.12+, or Node 26+. Use the development version in .nvmrc.
$ update-node [command]
Commands:
update-node bump-dependencies Upgrades defined dependencies and open Pull
request for them [aliases: upgrade, bd]
update-node auto-bump Auto Bump package version [aliases: version, ab]
update-node validate Validate a update-node configuration
[aliases: check]
update-node setup Scaffold a update-node configuration
[aliases: scaffold]
Options:
--version Show version number [boolean]
-l, --local Run in local mode with github publication
[boolean]
-v, --verbose More log outputs [boolean]
-t, --token Token to authentificate to github[string]
-a, --autoToken, --at, --auto-token Get authentificated github token from gh
cli [boolean]
-A, --auto Select automatically behavior to adopt
based on current commit and branch
[boolean]
-F, --folder Run in a specific folder [string]
-s, --scope Apply to a scope of the repository
(impact on title and branch name)[string]
-C, --config Override update-node configuration
default path [string]
-d, --default-config, --default Override update-node configuration
default path [boolean]
-c, --clean Run on a clean state [boolean]
--sync-lock Run npm install or yarn after patching
package.json (default, disable with
--no-sync-lock) [boolean] [default: true]
-b, --pre-commit-bump-command Command to run before to commit (changes
will be commited) [array]
-p, --pre-clean-command Run before to clean state [array]
-P, --post-clean-command Run on a clean state [array]
-f, --force Git Push with force changes
(--force-with-lease is used by default)
[boolean]
-h, --help Show help [boolean]
Upgrade related options:
-T, --target Node version to target [string]
--ignoreDependencies, --only-node Ignore depencies [boolean]
--lerna Consider as learna monorepo (only
applies for node bump) [boolean]
-m, --message Optional extra message to attach to the
commit and pull request [string]
-r, --reviewers Extra reviewers to add to the pull
request [string]
-R, --teamReviewers Extra team reviewers to add to the pull
request [string]
--exact Keep exact version in engine version
[boolean] [default: false]
--loose For loose version for nodes version.
This will replace exisiting range
constraint (^, ~ or none).
Use --no-loose to disable or place
loose: false in config in the node
section) [boolean] [default: true]
Examples
update-node --token=TKN
update-node -t TKN --config .my-update-node-config.jsonConfiguration goes in a .update-node.json at the top level of your repository.
Here are the main configuration items:
repoSlug: the github account + repo namereviewers,teamReviewers: array of reviewers or team reviewers, default[]baseBranch: the branch to target, defaultmasterlabel: the tabel to attach to the update Pull request (defaultUpgrades :outbox_tray:)packageManager: the package manager to use (defaultnpmunless ayarn.lock)
Three more complex items to configure the node bump logic, dependencies bump logic auto-bump, and the PR updates dependencies, see below in the sections below.
You can configure the ability to make a new version with the top level auto-bump key.
If you want the new package version to be publiished, just the the publish subproperty to true. (Default command npm publish, repleaceable with publish-command)
The default mecanism to select which semver level is based on a keyword mechanism. major, minor, patch that are provided to npm version. noop is also used to prevent a new version to be made.
For the bump, default keywords are the following
major:#majorminor:#noop#noRelease(was an accepted_or-between no and release)patch:#patch,#bug,#fix,#tweak,#updatesnoop:#minor
Order of preference is noop, major, parch, minor. If none match, the latest is selected. By default minor
You can either add your custom keywords with custom-keywords or replace default with yours using keywords. Both of them accept an object {[priority]: [keywordOrList]}. (if you have only one keyword pattern for one given semver level, you can just provide it as a string)/
Pattern matching is insensitive.
You can also provide minimatch glob patterns as value.
If ever you want a custom, external selection mecanism just put your command in the release-type-command property.
This property helps to configure the files that are related to a node version, and that you wish to be updated when trying the bump the node version.
When a Node upgrade synchronizes the lockfile or runs precommit bump commands, update-node requires a Node version manager. It prefers nvm (nvm use, then nvm install if needed), falling back to n auto when nvm is unavailable. These commands run with the activated Node version. If neither manager is available, the upgrade stops before changing version files with No node version manager was found. Upgrades with --no-sync-lock and no precommit commands do not require a manager.
When the primary package declares an engines.node range starting with >=, automatic upgrades prepare a separate alternative for each released, supported even Node major that matches the effective range. Current releases are included before LTS; prereleases and EOL majors are excluded. The latest release with an available exact Docker tag is selected for each major. An explicit --target or another engine range operator retains the single-upgrade behavior.
Each alternative starts from the same baseBranch commit. A new major raises the engine minimum to the selected full release and updates an existing npm engine to the bundled npm version. Within the same major, each package keeps its existing Node and npm engine ranges while configured version pins and lockfiles refresh. Set node.preserveSameMajor to false to raise engine minima within the same major as well. A candidate below any configured package's minimum is skipped. Lock synchronization and precommit commands explicitly activate the selected release, even when no .nvmrc is configured.
Branches use the configured prefix, scope, major and minor, such as update-node-api-v24.10. Patch updates reuse the branch and PR. After successfully publishing a newer minor, update-node closes older PRs carrying its generated metadata for the same major, scope, prefix and base. Local mode prepares independent local branches and commits. The original checkout is restored after each candidate; a clean tracked working tree is required. Failures are reported, other candidates continue, and the command exits unsuccessfully if any candidate failed. Unchanged candidates create no commit or PR.
Here is the list of config properties:
branch: the branch prefix for the node updates to be performpreserveSameMajor: preserve existing Node and npm engine ranges when the selected release is in the same Node major. Defaults totruefor automatic multi-version upgrades andfalsefor single-version upgrades, including explicit--targetrequests. An explicit boolean overrides either default; pins and lockfiles still refresh.nvrmc: should a.nvmrcfile be udpated (default true), can be an array of filesdockerfile: should a Dockerfile be udpated (default false), can be an array of filestravis: should a.travis.ymlbe udpated (default false), can be an array of filespackage: should package engine inpackage.jsonbe updated (default false), can be an array of files
The dependencies item is here to define the set of dependencies clusters you want to upgrade.
A cluster config have the following properties:
name: The name of the clustermessage: The name of the commit, and the Pull Requestbranch: The branch to use to open the pull requestdependencies: The (production) dependencies to be updated.devDependencies: The dev dependencies to be updated.
The dependecies can either be a full match, or a glob using minimatch. For instance eslint, eslint-plugin-* @babel/*
Here is the config of the repo itself:
{
"repoSlug": "Coorpacademy/update-node",
"baseBranch": "master",
"packageManager": "npm",
"reviewers": [],
"teamReviewers": [
"env:TEAM_REVIEWERS"
],
"label": "Upgrades :outbox_tray:",
"auto-bump": {
"publish": true,
"keywords": {
"noop": ["#noop", "Update *#*"],
"major": "#major",
"minor": true,
"patch": ["#bug", "#tweak", "plugging", "#updates"]
}
},
"node": false,
"dependencies": [
{
"name": "core",
"message": "Update core dependencies",
"branch": "update-core",
"dependencies": [
"bluebird",
"yaml",
"lodash",
"minimatch",
"yargs",
"protocall",
"request",
"semver",
"shelljs"
]
},
{
"name": "testing-tools",
"message": "Update Testing dependencies",
"devDependencies": [
"ava",
"istanbul",
"codecov",
"nyc"
]
},
{
"name": "eslint",
"message": "Update eslint",
"devDependencies": [
"eslint",
"@coorpacademy/eslint-plugin-coorpacademy"
]
}
]
}You can also check the validation schema or test sample