npm-pkg-lint

4.6.5 verified Fri May 01 auth: no javascript

Opinionated linter for NPM package tarball and package.json metadata, enforcing strict standards beyond spec validity. Current stable version is v4.6.5, with regular monthly bugfix releases. Key differentiators: focuses on production-quality packaging (disallowed files, dependency checks, exports order) rather than code style, integrates as GitHub Action, and can lint directly from tarballs or stdin. Supports Node.js ^20.18 || >= 22.16. Commonly used in CI pipelines to enforce consistent publishing practices.

Common errors

error Cannot find package 'npm-pkg-lint' from ↓

cause Package is not installed or not in node_modules.

fix

Run 'npm install npm-pkg-lint' to add it as a dev dependency.

error SyntaxError: Cannot use import statement outside a module ↓

cause Running ESM code in a CommonJS environment.

fix

Add '\"type\": \"module\"' to your package.json or use .mjs extension.

error Error: Unsupported Node.js version: 16.x ↓

cause Node.js 16 is below minimum required version.

fix

Upgrade Node.js to ^20.18 or >=22.16.

Warnings

breaking v3 dropped CommonJS support; require() no longer works. ↓

fix Use ESM imports (import { npmPkgLint } from 'npm-pkg-lint') or stay on v2.x.

breaking v4 renamed the rule 'no-exports-order' to 'exports-import-require-order'. ↓

fix Update your configuration to reference the new rule name.

breaking Minimum Node.js version increased from 14 to 20.18 in v4. ↓

fix Upgrade Node.js to ^20.18 or >=22.16.

deprecated The '--pkgfile' CLI argument is deprecated in favor of '--pkgfile' alias (same name, but new validation rules). ↓

fix Use '--pkgfile' as before; no immediate change needed, but prepare for removal in v5.

gotcha Using '--tarball -' (stdin) requires the tarball to be complete; piping a partial tarball will cause an error. ↓

fix Ensure the full tarball is piped; use 'cat' or 'curl' with appropriate flags to stream fully.

gotcha The '--allow-dependencies' option does not support scoped packages with slashes unless properly escaped. ↓

fix For scoped packages like '@scope/pkg', use the exact full name without escaping: '--allow-dependency @scope/pkg'.

deprecated Rule 'no-dev-dependencies-in-production' has been deprecated in favor of 'dependencies-in-production' (inverted logic). ↓

fix Rename the rule in your config and invert the boolean if needed.

Install

npm install npm-pkg-lint

yarn add npm-pkg-lint

pnpm add npm-pkg-lint

Imports

npmPkgLint
wrong
```
import npmPkgLint from 'npm-pkg-lint'
```
correct
```
import { npmPkgLint } from 'npm-pkg-lint'
```
Default export is not available; only named export exists. ESM-only package.
rules
wrong
```
const { rules } = require('npm-pkg-lint')
```
correct
```
import { rules } from 'npm-pkg-lint'
```
CommonJS require is not supported in v4+. The package is ESM-only since v3.
LintOptions
wrong
```
import { LintOptions } from 'npm-pkg-lint'
```
correct
```
import type { LintOptions } from 'npm-pkg-lint'
```
Type imports are required for types as the package does not use isolatedDeclarations; ensure your tsconfig includes 'verbatimModuleSyntax' or use `import type`.

Quickstart

Demonstrates programmatic usage: lint a tarball against its package.json, check validity, and exit with error if invalid.

import { npmPkgLint } from 'npm-pkg-lint';

const options = {
  pkgfile: './package.json',
  tarball: './my-pkg-1.2.3.tgz',
};

const result = await npmPkgLint(options);

if (result.valid) {
  console.log('Package is valid!');
} else {
  console.error('Lint errors:', result.errors);
  process.exit(1);
}