check-node-types 🔬

Keep @types/node in sync with your actual Node.js target.

The Problem

@types/node major versions map directly to Node.js releases: @types/node@22 provides types for Node.js 22.
If your project targets Node 20 but @types/node is ^22, TypeScript will happily let you use Node 22 APIs that don't exist at runtime.

No existing linter, ESLint plugin, or package manager catches this drift. We searched. Extensively.

Why Not Just…?

We evaluated every existing tool. None solve this.

| Tool | What it does | Why it's not enough | | ----------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Dependabot | Bumps @types/node to latest | Cannot update engines.node. Will bump @types/node past your target. | | Renovate | Can group engines.node + @types/node PRs | Groups updates but doesn't verify the majors match. Drift still possible from manual edits. | | syncpack | Enforces consistent versions across monorepos | Cannot cross-reference engines with devDependencies. | | npm-package-json-lint | Validates package.json fields | Has valid-values-engines but no cross-field comparison with dependency versions. | | eslint-plugin-package-json | Lints package.json | Has require-engines but nothing for dependency-to-engine consistency. | | ls-engines | Checks dependency tree engine compatibility | Checks engine requirements, not @types/node alignment. | | check-engine / check-node-version | Validates the running Node.js version | Checks the runtime, not the type definitions. | | @tsconfig/node bases | Sets target/module for a Node version | Doesn't set or validate @types/node. Using @tsconfig/node20 with @types/node@24 produces no error. | | Shell one-liners | Custom CI scripts | Work, but no standard solution — every team reinvents the wheel. |

The gap is well-documented: DefinitelyTyped Discussion #69418 is the canonical thread where maintainers and users discuss the lack of tooling for this.

The Recommended Workflow

check-node-types is designed as a companion to check-node-version. Together they cover both sides of the Node.js version problem:

| Tool | What it checks | | -------------------- | ------------------------------------------- | | check-node-version | Is the running Node.js version correct? | | check-node-types | Is the @types/node version correct? |

The recommended approach:

1. Exclude @types/node from automated dependency updates — tools like npm-check-updates or npm-check will always flag a new @types/node major as available, even when upgrading would be wrong for your project.
2. Use check-node-types in CI or as a lint step to verify that your @types/node stays in sync with your actual Node.js target.
3. When you intentionally upgrade Node.js, bump @types/node in the same commit.

This way you avoid the constant noise from update checkers, while still catching accidental drift.

Install

npm install -D check-node-types

Or run directly:

npx check-node-types

Usage

# Check using engines.node (default)
check-node-types

# Read Node.js version from different sources
check-node-types --source engines      # reads engines.node from package.json (default)
check-node-types --source volta        # reads volta.node from package.json
check-node-types --source nvmrc        # reads .nvmrc file
check-node-types --source node-version # reads .node-version file

# Point to a specific package.json
check-node-types --package ./packages/my-lib/package.json

# Print detected versions and exit
check-node-types --print

# Quiet mode — only output on error
check-node-types -q

# JSON output (for CI parsing)
check-node-types --json

As an npm script

{
	"scripts": {
		"check-types": "check-node-types"
	}
}

In CI (GitHub Actions)

- name: Verify @types/node matches target Node.js version
  run: npx check-node-types

In a Dockerfile

# Validate before installing dependencies
COPY package.json ./
RUN npx -y check-node-types
RUN npm ci

With lint-staged / Husky

{
	"lint-staged": {
		"package.json": ["check-node-types"]
	}
}

Options

| Flag | Short | Description | Default | | ------------------- | ----- | --------------------------------------------- | ---------------- | | --source <source> | | Where to read the Node.js version (see below) | engines | | --package <path> | | Path to package.json | ./package.json | | --print | | Print detected versions and exit | | | --quiet | -q | Only output on error | | | --json | | Output as JSON | | | --no-color | | Disable colored output | auto-detect |

Version Sources

| Source | Reads from | | -------------- | ------------------------------------------------------ | | engines | engines.node in package.json | | volta | volta.node in package.json | | nvmrc | .nvmrc file in same directory as package.json | | node-version | .node-version file in same directory as package.json |

Exit Codes

| Code | Meaning | | ---- | -------------------------------------------------------------------------------- | | 0 | Pass — versions match | | 1 | Fail — major version mismatch | | 2 | Warning — missing version source, missing @types/node, or unparseable versions |

Example Output

Pass:

check-node-types: PASS

Fail:

check-node-types: FAIL
  engines.node major:  20
  @types/node major:   22

  Fix: npm install -D @types/node@^20

Print:

engines.node: >=20 (major: 20)
@types/node: ^20.11.0 (major: 20)

How It Works

1. Reads the target Node.js version from the configured source (default: engines.node)
2. Reads the @types/node version from devDependencies or dependencies
3. Compares the major versions
4. Reports the result with an actionable fix command on mismatch

License

MIT