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
namestringDefines the specific npm package name
npmrcpathstringNpmrcPath defines the path to the .npmrc file
registrytokenstringRegistryToken defines the token to use when connection to the registry
urlstringURL defines the registry url (defaults to https://registry.npmjs.org/)
versionstringDefines a specific package version
versionfilterobjectVersionFilter provides parameters to specify version pattern and its type like regex, semver, or just latest.
    kindstringspecifies the version kind such as semver, regex, or latest
    patternstringspecifies the version pattern according the version kind for semver, it is a semver constraint for regex, it is a regex pattern for time, it is a date format
    regexstringspecifies the regex pattern, used for regex/semver and regex/time. Output of the first capture group will be used.
    replaceallobjectreplaceAll applies a regex replacement to version strings before filtering. This is useful for transforming versions (e.g., curl-8_15_0 to curl-8.15.0) before regex extraction.
    strictbooleanstrict enforce strict versioning rule. Only used for semantic versioning at this time
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 July 30, 2026
Prev
Maven Repository
Next
PyPI