Site: Planekeeper Docs — Monitor software versions across your stack. Planekeeper tracks releases, gathers version data, and alerts on drift.
Section: Recipes > Monitor Node.js dependencies
Source: https://docs.planekeeper.com/recipes/monitor-node-dependencies/
Title: Monitor Node.js dependencies
Author: Planekeeper
Description: Recipe for monitoring Node.js package versions by scraping package.json and tracking upstream releases from GitHub.
Word count: 568
Reading time: 3 min

Contents:
- [Prerequisites](#prerequisites)
- [Step 1: Create a gather job for the upstream package](#step-1-create-a-gather-job-for-the-upstream-package)
- [Step 2: Scrape your deployed version from package.json](#step-2-scrape-your-deployed-version-from-packagejson)
  - [Option A: Track the application version](#option-a-track-the-application-version)
  - [Option B: Track a specific dependency version](#option-b-track-a-specific-dependency-version)
  - [Option C: Use Regex for cleaner extraction](#option-c-use-regex-for-cleaner-extraction)
- [Step 3: Create a rule](#step-3-create-a-rule)
- [Step 4: Create an alert config](#step-4-create-an-alert-config)
- [Monitoring multiple dependencies](#monitoring-multiple-dependencies)

***

# 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+$` |

4. Click **Create**

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

> **info:** 
**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:

```json title="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) |

4. Click **Create**

### Option B: Track a specific dependency version

If you want to monitor a specific dependency:

```json title="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 * * *` |

2. Click **Create**

> **warning:** 
**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 |

4. 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` |

4. 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.

> **success:** 
**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.



---

## Related

- Next: [Send notifications to Discord](https://docs.planekeeper.com/recipes/discord-notifications/page.md) — Set up Discord webhook notifications with copy-paste templates for alert events.
- Section: [Recipes](https://docs.planekeeper.com/recipes/index.md)