Monitor Node.js dependencies

This recipe shows how to track Node.js package versions deployed in your applications. You will scrape version information from package.json and compare it against upstream GitHub releases.

---

Prerequisites

• A running Planekeeper instance with at least one active agent
• A Git repository containing a package.json file

---

Step 1: Create a gather job for the upstream package

Most popular npm packages host their releases on GitHub. Create a gather job pointing to the package's GitHub repository.

1. Navigate to Gather Jobs in the sidebar
2. Click Create Gather Job
3. Fill in the fields:

Field	Value
Name	Express.js Releases
Source Type	github_releases
Artifact Name	expressjs/express
Schedule	0 */12 * * * (every 12 hours)
Tag Filter	^\d+\.\d+\.\d+$

1. Click Create

The tag filter ^\d+\.\d+\.\d+$ ensures only clean semver tags are included, filtering out any non-release tags.

Finding the right GitHub repo

Check the npm package page for a link to the source repository. The repository field in the package's package.json on npm usually points to the correct GitHub repo.

---

Step 2: Scrape your deployed version from package.json

Option A: Track the application version

If your package.json contains your application's own version:

package.json

{
  "name": "my-api",
  "version": "2.1.0"
}

1. Navigate to Scrape Jobs in the sidebar
2. Click Create Scrape Job
3. Fill in the fields:

Field	Value
Name	My API Version
Repository URL	https://github.com/myorg/my-api.git
Target File	package.json
Parser Type	jq
Parse Expression	.version
Schedule	0 9 * * * (daily at 9am)

1. Click Create

Option B: Track a specific dependency version

If you want to monitor a specific dependency:

package.json

{
  "dependencies": {
    "express": "^4.18.2",
    "lodash": "^4.17.21"
  }
}

1. Create a scrape job with:

Field	Value
Name	Express Dependency Version
Repository URL	https://github.com/myorg/my-api.git
Target File	package.json
Parser Type	jq
Parse Expression	.dependencies.express
Schedule	0 9 * * *

1. Click Create

Version range prefixes

The JQ parser extracts the raw value, which may include prefixes like ^, ~, or >=. If upstream releases store bare versions (e.g., 4.18.2), you need to strip the prefix. Use the Regex parser instead with an expression like "express":\s*"[^~>=]*?([\d.]+)" to extract only the numeric version.

Option C: Use Regex for cleaner extraction

For dependency versions with range prefixes, the Regex parser gives more control:

Field	Value
Parser Type	regex
Parse Expression	"express":\s*"[\^~>=]*([\d.]+)"

This strips any ^, ~, >= prefix and extracts only the version number.

---

Step 3: Create a rule

1. Navigate to Rules in the sidebar
2. Click Create Rule
3. Fill in the fields:

Field	Value
Name	NPM Package Majors Behind
Rule Type	majors_behind
Moderate Threshold	1
High Threshold	2
Critical Threshold	3
Stable Only	Checked

1. Click Create

---

Step 4: Create an alert config

1. Navigate to Alert Configs in the sidebar
2. Click Create Alert Config
3. Fill in the fields:

Field	Value
Name	Express Version Check
Scrape Job	Select Express Dependency Version
Gather Job	Select Express.js Releases
Rule	Select NPM Package Majors Behind

1. Click Create

---

Monitoring multiple dependencies

To monitor several dependencies from the same repository, create separate scrape jobs for each one -- each with a different parse expression targeting the specific dependency.

Dependency	Parse expression (JQ)	Parse expression (Regex)
express	.dependencies.express	"express":\s*"[\^~>=]*([\d.]+)"
lodash	.dependencies.lodash	"lodash":\s*"[\^~>=]*([\d.]+)"
axios	.dependencies.axios	"axios":\s*"[\^~>=]*([\d.]+)"

Each scrape job pairs with its own gather job (pointing to the dependency's GitHub repo) and shares the same rule through separate alert configs.

Reuse rules across dependencies

Create one rule like "NPM Package Majors Behind" and use it in every alert config. You only need different gather and scrape jobs per dependency.