Updatecli
Docs

NPM

Description

The npm crawler looks recursively for every package.json file from a specific root directory, and tries to update the dependencies declared in dependencies and devDependencies.

This crawler is enabled by default, so it can be used either automatically by running updatecli diff from a directory containing the files to update, or by providing a manifest. The automatic discovery behavior can be tuned by providing a YAML manifest with an npm crawler in top-level directive autodiscovery as explained in the "Autodiscovery" page.

Requirements

What the crawler generates depends on which lock file sits next to package.json, and on which package manager is installed where Updatecli runs.

Lock fileCommand availableResult

none

-

package.json is updated on its own. Nothing refreshes a lock file, because there is none.

package-lock.json

npm

A shell target runs npm install --package-lock-only to refresh the lock file.

yarn.lock

yarn

A shell target refreshes yarn.lock. See the note on npm 8 below.

pnpm-lock.yaml

pnpm

A shell target runs pnpm add --lockfile-only.

any of the above

its command missing

The whole package.json is skipped, with a warning. Updatecli will not bump a dependency it cannot re-lock.

Important
The lock file decides which command is required, not what is installed. A project with a yarn.lock is skipped when yarn is absent, even when npm is available.

Dry-run support

npm version 8 and later can update a yarn.lock, and unlike yarn it supports a dry run. So when a yarn.lock is found and npm is recent enough, Updatecli generates the npm command in preference to the yarn one.

Warning
When Updatecli has to fall back to yarn add --mode update-lockfile or pnpm add --lockfile-only, neither supports a dry run. updatecli diff will then modify the lock file on disk rather than only reporting the change. Installing npm 8 or later avoids this for yarn projects.

Generated manifests

Each dependency produces an npm source resolving the latest published version and a json target writing it back into package.json, plus the lock-file shell target described above when one applies.

Version constraints

A dependency declared with a range, such as ^4.18.0 or ~29.7.0, keeps that constraint by default: the range is respected when looking for a newer version.

Set ignoreversionconstraints: true to disregard the declared range and offer the latest published version instead.

Manifest

Parameters

NameTypeDescriptionRequired
ageobject

“age” defines the minimum or maximum age of a release to be considered valid.

default:

age:
  minimum: 3d

remark:

  • it accepts a duration string, such as “24h”, “7d”, “3w” or “1y”.
  • it is propagated to the generated npm sources.
  • the default keeps Updatecli from suggesting a package version published less than three days ago.
  • an empty “age: {}” disables the default.
  • it cannot be combined with “vulnerability”.
    maximumstring

“maximum” defines the maximum age a release may have to be considered.

remark:

  • accepted units are “d” for days, “w” for weeks, “mo” for months and “y” for years, plus the Go duration units such as “h”, “m” and “s”.
  • a unit is required.
  • a month counts as 1/12 of a year and a year as 365 days.

example:

  • maximum: 6mo
  • maximum: 1y
    minimumstring

“minimum” defines the minimum age a release must have to be considered.

remark:

  • accepted units are “d” for days, “w” for weeks, “mo” for months and “y” for years, plus the Go duration units such as “h”, “m” and “s”.
  • a unit is required.
  • a month counts as 1/12 of a year and a year as 365 days.

example:

  • minimum: 24h
  • minimum: 7d
  • minimum: 3w
ignorearray

“ignore” defines rules to exclude matching npm packages from the autodiscovery.

remark:

  • a npm package is ignored when it matches at least one rule.
    hasversionconstraintboolean

“hasversionconstraint” defines whether the package must be declared with a version constraint.

example:

  • hasversionconstraint: true
    packagesobject

“packages” defines the npm packages to match, keyed by package name.

remark:

  • an empty value matches any version.
  • otherwise the value is a semantic version constraint, such as “>=1.0.0”.
  • when the version or the constraint cannot be parsed, the value must equal the version.
    pathstring

“path” defines a package.json path pattern.

remark:

  • the pattern must match the whole path, not just a substring.
  • the pattern follows the Go filepath.Match syntax, such as “*” or “?”.
ignoreversionconstraintsboolean

“ignoreversionconstraints” defines whether the version constraints set in package.json are ignored.

When true, a package declared with a version constraint is updated to the latest version accepted by “versionfilter”, instead of the latest version accepted by the constraint.

default: false

remark:

  • when true and “versionfilter” is set, Updatecli converts the constraint to a version so “versionfilter” can select the next patch, minor or major version. A complex constraint, such as “>=1.0.0 <2.0.0”, is converted to the first version it holds, 1.0.0 in this example.
  • it cannot be combined with “vulnerability”.
npmrcpathstring

“npmrcpath” defines the path of the .npmrc file used by every discovered package.

remark:

  • it is propagated to the generated npm resources.
onlyarray

“only” defines rules to restrict the autodiscovery to matching npm packages.

remark:

  • a npm package is kept only when it matches at least one rule.
    hasversionconstraintboolean

“hasversionconstraint” defines whether the package must be declared with a version constraint.

example:

  • hasversionconstraint: true
    packagesobject

“packages” defines the npm packages to match, keyed by package name.

remark:

  • an empty value matches any version.
  • otherwise the value is a semantic version constraint, such as “>=1.0.0”.
  • when the version or the constraint cannot be parsed, the value must equal the version.
    pathstring

“path” defines a package.json path pattern.

remark:

  • the pattern must match the whole path, not just a substring.
  • the pattern follows the Go filepath.Match syntax, such as “*” or “?”.
registrytokenstring

“registrytoken” defines the token used to authenticate with the registry.

remark:

  • it is propagated to the generated npm sources.
rootdirstring

“rootdir” defines the directory where the crawler starts searching for package.json files.

default: the scm directory when “scmid” is set, otherwise the directory relative paths resolve from, by default the working directory.

remark:

  • a relative path is resolved from the default directory.
  • an absolute path is used as is, instead of the scm directory.
urlstring

“url” defines the npm registry url.

default: https://registry.npmjs.org/

remark:

  • it is propagated to the generated npm sources.
versionfilterobject

“versionfilter” defines the version filter used by the generated manifests.

default:

  • an exact version: kind “semver” with pattern “>=”.
  • a version constraint: kind “semver” with the constraint as pattern, or “*” when “ignoreversionconstraints” is true.

remark:

  • with kind “semver”, “pattern” accepts:
    • “prerelease”: the latest prerelease of the current version.
    • “patch”: patch updates only.
    • “minor”: patch and minor updates.
    • “minoronly”: minor updates only.
    • “major”: patch, minor and major updates.
    • “majoronly”: major updates only.
    • a version constraint, such as “>= 1.0.0”.
  • with kind “regex”, “pattern” accepts a regular expression.
  • more examples at https://www.updatecli.io/docs/core/versionfilter/
  • it is ignored for a package declared with a version constraint, unless “ignoreversionconstraints” is true.
  • it cannot be combined with “vulnerability”.

example:

versionfilter:
  kind: semver
  pattern: minor
    kindstring

“kind” defines the versioning scheme used to select a version.

default: latest

remark:

  • accepted values are “latest”, “semver”, “regex”, “regex/semver”, “time”, “regex/time”, “lex” and “pep440”.
  • “latest” returns the last version of the list.
  • “lex” sorts the versions lexicographically and returns the last one.
  • “pep440” follows https://peps.python.org/pep-0440/

example:

  • kind: semver
    patternstring

“pattern” defines the version pattern, according to “kind”.

default:

  • latest: “latest”
  • semver and pep440: “*”
  • regex: “.*”
  • time and regex/time: “2006-01-02”

remark:

  • for “latest”, “latest” returns the last version, any other value must match a version exactly.
  • for “semver” and “regex/semver”, it is a semantic versioning constraint.
  • for “pep440”, it is a pep440 version specifier.
  • for “regex”, it is a regular expression.
  • for “time” and “regex/time”, it is a Go date layout.
  • ignored by “lex”.

example:

  • pattern: ~1.2
  • pattern: “>=1.0.0 <2.0.0”
  • pattern: ^v\d+.\d+.\d+$
    regexstring

“regex” defines the regular expression extracting the version from each entry.

remark:

  • only used by the kinds “regex/semver” and “regex/time”.
  • the value of the first capture group is used as the version.

example:

  • regex: ^v(\d+.\d+.\d+)$
    replaceallobject

“replaceall” applies a regular expression replacement to each version before filtering.

remark:

  • only used by the kinds “regex”, “regex/semver” and “regex/time”.
  • the replacement runs before “pattern” or “regex” is evaluated.

example:

replaceall:
  pattern: "_"
  replacement: "."

turns “curl-8_15_0” into “curl-8.15.0”.

        patternstring

“pattern” defines the regular expression matching the text to replace.

example:

  • pattern: “_”
        replacementstring

“replacement” defines the text replacing each match of “pattern”.

remark:

  • capture groups can be referenced with $1, $2, and so on.

example:

  • replacement: “.”
    strictboolean

“strict” enforces strict semantic versioning rules when parsing versions.

default: false

remark:

  • only used by the kinds “semver” and “regex/semver”.
vulnerabilityobject

“vulnerability” switches the autodiscovery to security updates, based on the OSV database (https://osv.dev).

A package is only updated when its current version has known vulnerabilities, to the lowest version without any.

remark:

  • only security updates are generated, routine updates require a separate manifest.
  • it cannot be combined with “age”, “versionfilter” and “ignoreversionconstraints”.
  • the default minimum release age does not apply, a fixed version is suggested as soon as it is known.
  • the current version is the exact version from package.json or, for a version constraint, the version resolved in the package-lock.json, pnpm-lock.yaml or yarn.lock next to it, or at the root of its workspace. Packages without an identifiable current version are ignored.
  • labels, such as “security”, are set on the action used by the manifest.

example:

vulnerability:
  minseverity: high
  ignore:
    - GHSA-jr5f-v2jv-69x6
    ignorearray

“ignore” defines the vulnerability IDs or aliases to disregard.

example:

ignore:
  - GO-2025-3503
  - GHSA-cpwx-vrp4-4pq7
  - CVE-2025-27516
    minseveritystring

“minseverity” defines the minimum severity of the vulnerabilities to account for.

remark:

  • accepted values are “LOW”, “MODERATE”, “HIGH” and “CRITICAL”, in any case.
  • “MEDIUM” is accepted as an alias of “MODERATE”.
  • the severity comes from GitHub advisories. Vulnerabilities without one are always accounted for.

example:

  • minseverity: HIGH
    strategystring

“strategy” defines the version a vulnerable dependency is updated to.

default: lowest

remark:

  • the only accepted value is “lowest”: the lowest version without known vulnerabilities.
  • the value is case insensitive.
    urlstring

“url” defines the OSV API URL.

default: https://api.osv.dev

⚠ This table is generated from the Updatecli codebase and may contain inaccurate data. Feel free to report them on github.com/updatecli/updatecli

Example

Basic Example

# updatecli.d/npm.yaml
autodiscovery:
  crawlers:
    npm:
      rootdir: "."
      versionfilter:
        kind: semver
        pattern: minor

Private Registry Example

The following example shows how to configure npm autodiscovery to work with a private npm registry:

# updatecli.d/npm-private.yaml
autodiscovery:
  crawlers:
    npm:
      rootdir: "."
      # URL of your private npm registry
      url: "https://npm.example.com"
      # Authentication token (use environment variables for security)
      registrytoken: "${NPM_TOKEN}"
      # Optional: path to custom .npmrc file
      npmrcpath: "/path/to/.npmrc"
      versionfilter:
        kind: semver
        pattern: ">=1.0.0"
Note
The url, registrytoken, and npmrcpath parameters are propagated to all generated npm resource specs, allowing consistent authentication across all discovered dependencies.
Last updated on September 26, 2026
Prev
Nomad
Next
Precommit