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
ignorearrayIgnore allows to specify rule to ignore autodiscovery a specific NPM based on a rule
    hasversionconstraintbooleanHasVersionConstraint indicates whether the matching rule should match any version constraint or not.
    packagesobjectPackages specifies the list of NPM packages to check
    pathstringPath specifies a package.json path pattern, the pattern requires to match all of name, not just a substring.
ignoreversionconstraintsboolean

IgnoreVersionConstraints indicates whether to respect version constraints defined in package.json or not. When set to true, Updatecli will ignore version constraints and update to the latest version available in the registry according to the specified version filter. Default is false.

Remark:

  • If set to false, Updatecli will try to convert version constrains to valid semantic version so we can use versionFilter to retrieve the last Major/Minor/Patch version but in case of complex version constraints, such as >=1.0.0 <2.0.0, Updatecli will convert it to the first version it detects such as 1.0.0 in our example
npmrcpathstringNpmrcPath defines the path to the .npmrc file to use for all discovered packages. This will be propagated to all generated npm resource specs.
onlyarrayOnly allows to specify rule to only autodiscover manifest for a specific NPM based on a rule
    hasversionconstraintbooleanHasVersionConstraint indicates whether the matching rule should match any version constraint or not.
    packagesobjectPackages specifies the list of NPM packages to check
    pathstringPath specifies a package.json path pattern, the pattern requires to match all of name, not just a substring.
registrytokenstringRegistryToken defines the token to use when connecting to the registry. This will be propagated to all generated npm resource specs.
rootdirstringRootDir defines the root directory used to recursively search for npm packages.json
urlstringURL defines the registry url (defaults to https://registry.npmjs.org/). This will be propagated to all generated npm resource specs.
versionfilterobject

versionfilter provides parameters to specify the version pattern used when generating manifest.

kind - semver versionfilter of kind semver uses semantic versioning as version filtering pattern accepts one of: prerelease - Updatecli tries to identify the latest prerelease whatever it means patch - Updatecli only handles patch version update minor - Updatecli handles patch AND minor version update minoronly - Updatecli handles minor version only major - Updatecli handles patch, minor, AND major version update majoronly - Updatecli only handles major version update a version constraint such as >= 1.0.0

kind - regex versionfilter of kind regex uses regular expression as version filtering pattern accepts a valid regular expression

example:

  versionfilter:
    kind: semver
    pattern: minor

and its type like regex, semver, or just latest.

More examples can be found at https://www.updatecli.io/docs/core/versionfilter/

    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.
        patternstringPattern specifies the regex pattern to match for replacement
        replacementstringReplacement specifies the replacement string (supports $1, $2, etc. for captured groups)
    strictbooleanstrict enforce strict versioning rule. Only used for semantic versioning at this time
⚠ 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 July 30, 2026
Prev
Nomad
Next
Precommit