npm-pkg-lint

library4.6.5jsnpmunverified

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.

devops testing

npm install npm-pkg-lint

github ↗package ↗

INSTALL

IMPORT

SIG · NPM-PKG-LINT

npm-pkg-lint

devopsjavascriptv4.6.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

npmPkgLint

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

✗ import npmPkgLint from 'npm-pkg-lint'

Default export is not available; only named export exists. ESM-only package.

rules

✓ import { rules } from 'npm-pkg-lint'

✗ const { rules } = require('npm-pkg-lint')

CommonJS require is not supported in v4+. The package is ESM-only since v3.

LintOptions

✓ import type { LintOptions } from 'npm-pkg-lint'

✗ import { 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`.

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); }

npm-pkg-lint --version

Debug

Known issues

breakingv3 dropped CommonJS support; require() no longer works.

fix

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

affects: >=3.0.0

breakingv4 renamed the rule 'no-exports-order' to 'exports-import-require-order'.

fix

Update your configuration to reference the new rule name.

affects: >=4.0.0

breakingMinimum Node.js version increased from 14 to 20.18 in v4.

fix

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

affects: >=4.0.0

deprecatedThe '--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.

affects: >=4.0.0

gotchaUsing '--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.

affects: all

gotchaThe '--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'.

affects: >=4.0.0

deprecatedRule '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.

affects: >=4.0.0

Errors

Common errors & fixes

Cannot find package 'npm-pkg-lint' from

Package is not installed or not in node_modules.

fix

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

SyntaxError: Cannot use import statement outside a module

Running ESM code in a CommonJS environment.

fix

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

Error: Unsupported Node.js version: 16.x

Node.js 16 is below minimum required version.

fix

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

Upgrade

Version history

4.6.5latest on npm

Audit

Dependencies

@html-validate/stylishrequiredFormatter for lint output

tarrequiredExtract tarball contents

nano-spawnrequiredSpawn child processes for npm pack/build

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/ext/npm-pkg-lint ↗

packagehttps://www.npmjs.com/package/npm-pkg-lint ↗