Npm integration

Overview

NPM (Node Package Manager) is the default package manager for Node.js. This tool interacts with npm-compatible registries (npmjs.org, GitHub Packages, Verdaccio, Artifactory, etc.) via their HTTP API. It supports two resources: Package (get metadata at a specific version, get all versions, search packages) and Distribution Tag (get all dist-tags, update a dist-tag). Authentication is optional — only required for write operations (dist-tag update) or private registry access. The credential provides an access token and a configurable registry URL (defaults to https://registry.npmjs.org).

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires Npm API credentials. See the Credentials Guide for setup instructions.

Resources

Resource	Value
Package	package
Distribution Tag	distTag

Operations

Package

Operation	Value	Description
Get Metadata	getMetadata	Returns all the metadata for a package at a specific version
Get Versions	getVersions	Returns all the versions for a package
Search	search	Search for packages

Distribution Tag

Operation	Value	Description
Get All	getMany	Returns all the dist-tags for a package
Update	update	Update a dist-tag for a package

Parameters

Package: Get Metadata

Parameter	Type	Required	Default	Description
Package Name	string	Yes	—	The name of the npm package. Supports scoped packages (e.g., @scope/package).
Package Version	string	Yes	latest	A package version, as a semver string (e.g. 1.2.3) or, when retrieving metadata, a dist-tag such as latest.

Package: Get Versions

Parameter	Type	Required	Default	Description
Package Name	string	Yes	—	The name of the npm package. Supports scoped packages (e.g., @scope/package).

Package: Search

Parameter	Type	Required	Default	Description
Query	string	Yes	—	The query text used to search for packages.
Limit	number	No	10	Max number of results to return.
Offset	number	No	0	Offset to return results from (for pagination).

Distribution Tag: Get All

Parameter	Type	Required	Default	Description
Package Name	string	Yes	—	The name of the npm package. Supports scoped packages (e.g., @scope/package).

Distribution Tag: Update

Parameter	Type	Required	Default	Description
Package Name	string	Yes	—	The name of the npm package. Supports scoped packages (e.g., @scope/package).
Package Version	string	Yes	—	A package version, as a semver string (e.g. 1.2.3) or, when retrieving metadata, a dist-tag such as latest.
Distribution Tag Name	string	Yes	latest	The name of the distribution tag to update (e.g., latest, next, beta).

All Operations

Parameter	Type	Required	Default	Description
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

The registry response is merged onto the input item JSON — the fields already on the item pass through and the result is written on top of them. Binary data is forwarded unchanged.

Operation	Output items per input item
package / getMetadata	One item carrying the full registry metadata document for that version
package / getVersions	Fans out — one item per published version, each { version, published_at }, newest first
package / search	Fans out — one item per match, each { name, version, description }
distTag / getMany	One item whose properties are the dist-tag names mapped to versions
distTag / update	One item carrying the registry’s response to the tag update

getVersions and search return a trimmed shape rather than the raw registry payload: version listings are filtered to valid semver entries and sorted by publish date, and search results are reduced to name, version and description. If an operation produces no results at all, the input item still passes through as a single output item with nothing added.

Reference the result downstream by expression, e.g. {{ $json.version }}.

Example Configuration

Fetch the metadata document for a package at a given version:

{
  "type": "npm",
  "parameters": {
    "resource": "package",
    "operation": "getMetadata",
    "packageName": "{{ $json.packageName }}",
    "packageVersion": "latest"
  }
}

List every published version of a scoped package:

{
  "type": "npm",
  "parameters": {
    "resource": "package",
    "operation": "getVersions",
    "packageName": "@typescript-eslint/parser"
  }
}

Search the registry with pagination:

{
  "type": "npm",
  "parameters": {
    "resource": "package",
    "operation": "search",
    "query": "workflow automation",
    "limit": 50,
    "offset": 0
  }
}

Read the current dist-tags for a package:

{
  "type": "npm",
  "parameters": {
    "resource": "distTag",
    "operation": "getMany",
    "packageName": "express"
  }
}

Point a dist-tag at a newly published version:

{
  "type": "npm",
  "parameters": {
    "resource": "distTag",
    "operation": "update",
    "packageName": "{{ $json.packageName }}",
    "distTagName": "beta",
    "packageVersion": "{{ $json.newVersion }}"
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

This tool queries npm registries to search for packages, retrieve package metadata and versions, and manage distribution tags. It is ideal when you need to find packages, inspect their details, or control how versions are referenced by distribution tags. It produces package search results, package metadata, lists of versions, and distribution tag information.