GitHub Packages · MIT · Node ≥ 18
Make engines.node, your CI matrix, .nvmrc and your dependencies' engine requirements agree.
1 Point the @mrlouiswright scope at GitHub Packages in .npmrc
@mrlouiswright:registry=https://npm.pkg.github.com2 Install
npm i -D @mrlouiswright/engines-gaugePublished to GitHub Packages, not npmjs.com. GitHub Packages needs a GitHub token with read:packages to install, even for public packages: add //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN} to .npmrc or run npm login --registry=https://npm.pkg.github.com.
$ npx engines-gaugeengines-gauge — my-lib@1.0.0engines.node ">=16"; CI: 14, 20, 22; pins: .nvmrc 15, volta 14.21.3; deps need ≥ 18.17.0 (fast-lib@5.1.0) HIGH .nvmrc:1 .nvmrc pins Node 15, outside engines.node ">=16" [nvmrc-outside-engines] ↳ fix: Pin a version engines.node allows (e.g. 16), or update engines.node.HIGH package-lock.json:4 fast-lib@5.1.0 requires node ">=18.17", but engines.node ">=16" allows Node 16, 17 [dependency-engines-conflict] ↳ fix: Raise engines.node to ">=18.17.0" (or pin an older fast-lib that still supports Node 16).MEDIUM .github/workflows/ci.yml:9 CI runs Node 14 (matrix.node-version) but engines.node ">=16" does not allow it [ci-outside-engines] ↳ fix: Remove it from the matrix or widen engines.node.MEDIUM package.json:5 package.json (volta.node) pins Node 14.21.3, outside engines.node ">=16" [runtime-pin-outside-engines] ↳ fix: Pin a version engines.node allows (e.g. 16), or update engines.node.LOW .nvmrc:1 .nvmrc pins Node 15 but CI never runs 15 [ci-missing-pinned] ↳ fix: Add 15 to the matrix (or use node-version-file: .nvmrc).... 2 high, 2 medium, 3 low, 3 info✔ Passing (fail-on: none).
engines.node is a promise to your users, and it drifts. CI quietly stops testing the minimum you claim. .nvmrc pins a version that engines forbids. A dependency update starts requiring Node 18.17 while your package.json still says “>=16”, so users on 16 get a broken install. engines-gauge reads every place a Node.js version is declared, cross-checks them, and reports each mismatch with the file, line, severity and a concrete fix.
CLI, library and GitHub Action. Node.js 18+, zero runtime dependencies. By Louis Wright.
engines.node; GitHub Actions setup-node (literal versions, node-version-file, and ${{ matrix.* }} lists in flow, block and include: form); .nvmrc, .node-version, .tool-versions, Volta and Dockerfile FROM node:*; and @types/node.
read from package-lock.json (v2/v3) or installed node_modules. Production and dev dependencies are checked separately and optional ones are skipped. The fix tells you the minimum engines.node that satisfies everything you ship.
resolves lts/*, lts/iron, lts/-1, node and 22.x, and flags end-of-life lines (as info, so supporting older Node is your call).
text, JSON, SARIF 2.1.0 and Markdown; --fail-on; exit codes 0/1/2; allowlist entries with expiry dates.
# run in the package directory
npx engines-gauge# Example
npx engines-gauge --fail-on medium# Example
npx engines-gauge --ignore-deps "fsevents,@esbuild/*"# CI must test the engines minimum even if it is EOL
npx engines-gauge --strict-minimumpermissions:
contents: read
security-events: write # only needed for the SARIF upload
jobs:
engines-gauge:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with: { persist-credentials: false }
- uses: MrLouisWright/engines-gauge@v1
with:
fail-on: high
sarif: engines-gauge.sarif
- uses: github/codeql-action/upload-sarif@v3
if: always()
with: { sarif_file: engines-gauge.sarif }| Flag | Description |
|---|---|
| Checks | |
--ignore-deps <globs> | Dependencies whose engines are ignored (comma-separated) |
--strict-minimum | Require CI to test the engines minimum even if it is end-of-life |
--require-engines | Report missing engines.node even for private packages |
| Common | |
-c, --config <file> | JSON config (default: .engines-gauge.json or "enginesGauge" in package.json) |
-f, --format <fmt> | text (default) | json | sarif | markdown |
--json <file> | Also write a JSON report |
--sarif <file> | Also write SARIF 2.1.0 |
--markdown <file> | Also write Markdown (e.g. for a job summary) |
--fail-on <sev> | critical | high | medium | low | info | none (default: high) |
--list-rules | Print rules and default severities |
--no-fixes | Hide fix suggestions in text output |
--no-color | Disable colours |
Full reference, config file format and API in the README.
Support this project
I build free, open-source tools that help developers ship safer websites. Every coffee helps keep them maintained, documented and free for everyone.
Buy me a coffee (opens Stripe in a new tab)Secure checkout by Stripe
