Updatecli
Docs

NPM

sourceconditiontarget

✔

✔

✗

Description

The npm resource queries an npm registry for the versions of a package.

source

Returns the version of the package matching versionfilter.

condition

Checks that version is published for the package.

target

Not supported - a registry is not something Updatecli publishes to. A target fails with Target not supported for the plugin Npm. To bump a dependency in a file, use the "JSON" resource against package.json, or the npm autodiscovery crawler.

Note
An scm attached to a condition is ignored, with a warning (the lookup always goes to the registry).

Parameters

NameTypeDescriptionRequired
ageobject

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

compatible:

  • source
  • condition

remark:

  • the release dates are read from the “time” object returned by the npm registry, so no extra API call is needed. Versions without a release date are ignored.
  • when “age” is combined with a “latest” versionfilter and the “latest” dist-tag is too recent, Updatecli falls back to the most recently published non prerelease version matching the age window, which may not be the highest semantic version. Combine “age” with a “semver” versionfilter to control ordering.
  • a source is skipped, not failed, when no version matches the age window yet.

example:

  • age: minimum: 7d
    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
namestring

“name” defines the npm package name.

compatible:

  • source
  • condition

remark:

  • “name” is required.

example:

  • name: axios
  • name: “@updatecli/example”
npmrcpathstring

“npmrcpath” defines the path of the .npmrc file.

compatible:

  • source
  • condition

default: $HOME/.npmrc

remark:

  • the default is also used when the file does not exist.
  • registry tokens and scoped registries are read from this file.
registrytokenstring

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

compatible:

  • source
  • condition
urlstring

“url” defines the npm registry url.

compatible:

  • source
  • condition

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

remark:

  • a scoped package uses the registry that the .npmrc file sets for its scope, if any.
versionstring

“version” defines the package version to check.

compatible:

  • condition

default: the output of the associated source.

versionfilterobject

“versionfilter” defines the version pattern and its kind, such as “regex”, “semver” or “latest”.

compatible:

  • source

default: latest

remark:

  • with the kind “latest”, the version is the “latest” dist-tag of the package.
    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”.

    strictboolean

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

default: false

remark:

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

The package name, scope included: @updatecli/updatecli as well as express.

url

Defaults to https://registry.npmjs.org/.

version

Condition only - the version whose existence is being checked.

Version selection

versionfilter behaves differently here than on most resources: with kind: latest, the value is taken from the registry’s own dist-tags.latest, which is what npm install <pkg> would give you (not the highest version number).

Every other filter kind sorts the full version list and applies the pattern. That distinction matters for packages that publish patches for older majors after a new major: latest follows the maintainer’s tag, semver follows the numbering. See the "Version Filtering" page.

Authentication

Private registries are reached in one of two ways.

registrytoken sets the bearer token directly, keep it out of the manifest:

spec:
  name: "@acme/widget"
  url: "https://npm.acme.example.com"
  registrytoken: '{{ requiredEnv "NPM_TOKEN" }}'

npmrcpath points at an .npmrc file instead. Its handling has a fallback worth knowing about:

Important

When npmrcpath is empty or the file it names does not exist, Updatecli falls back to $HOME/.npmrc. A typo in the path therefore does not raise an error (it silently reads the user’s own configuration, which is easy to miss when it works locally and fails in CI where that file is absent).

From an .npmrc, Updatecli reads two kinds of entry:

  • //registry.example.com/:_authToken=xxx - a token per registry

  • @scope:registry=https://registry.example.com - a registry per scope

Example

# updatecli.yaml
name: NPM resource example
sources:
  axios: 
    name: Get latest axios version from npm registry
    kind: npm
    spec: 
      name: axios
  yaml:
    name: get latest yaml version matching ~0
    kind: npm
    spec: 
      name: yaml
      versionfilter: 
        kind: semver
        pattern: ~0
conditions:
  axios: 
    name: Test that axios version 1.0.0 exists on the NPM registry
    kind: npm
    disablesourceinput: true
    spec: 
      name: axios
      version: 1.0.0
  yaml:
    name: Test that that YAML version matching ~0 exist on registry
    kind: npm
    sourceid: yaml
    spec: 
      name: yaml
targets:
  # Targets are not supported

Links

Last updated on August 2, 2026
Prev
Maven Repository
Next
PyPI