{"id":26020,"library":"npm-pkg-lint","title":"npm-pkg-lint","description":"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.","status":"active","version":"4.6.5","language":"javascript","source_language":"en","source_url":"https://github.com/ext/npm-pkg-lint","tags":["javascript","lint","npm"],"install":[{"cmd":"npm install npm-pkg-lint","lang":"bash","label":"npm"},{"cmd":"yarn add npm-pkg-lint","lang":"bash","label":"yarn"},{"cmd":"pnpm add npm-pkg-lint","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Formatter for lint output","package":"@html-validate/stylish","optional":false},{"reason":"Extract tarball contents","package":"tar","optional":false},{"reason":"Spawn child processes for npm pack/build","package":"nano-spawn","optional":false}],"imports":[{"note":"Default export is not available; only named export exists. ESM-only package.","wrong":"import npmPkgLint from 'npm-pkg-lint'","symbol":"npmPkgLint","correct":"import { npmPkgLint } from 'npm-pkg-lint'"},{"note":"CommonJS require is not supported in v4+. The package is ESM-only since v3.","wrong":"const { rules } = require('npm-pkg-lint')","symbol":"rules","correct":"import { rules } from 'npm-pkg-lint'"},{"note":"Type imports are required for types as the package does not use isolatedDeclarations; ensure your tsconfig includes 'verbatimModuleSyntax' or use `import type`.","wrong":"import { LintOptions } from 'npm-pkg-lint'","symbol":"LintOptions","correct":"import type { LintOptions } from 'npm-pkg-lint'"}],"quickstart":{"code":"import { npmPkgLint } from 'npm-pkg-lint';\n\nconst options = {\n  pkgfile: './package.json',\n  tarball: './my-pkg-1.2.3.tgz',\n};\n\nconst result = await npmPkgLint(options);\n\nif (result.valid) {\n  console.log('Package is valid!');\n} else {\n  console.error('Lint errors:', result.errors);\n  process.exit(1);\n}","lang":"typescript","description":"Demonstrates programmatic usage: lint a tarball against its package.json, check validity, and exit with error if invalid."},"warnings":[{"fix":"Use ESM imports (import { npmPkgLint } from 'npm-pkg-lint') or stay on v2.x.","message":"v3 dropped CommonJS support; require() no longer works.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update your configuration to reference the new rule name.","message":"v4 renamed the rule 'no-exports-order' to 'exports-import-require-order'.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade Node.js to ^20.18 or >=22.16.","message":"Minimum Node.js version increased from 14 to 20.18 in v4.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use '--pkgfile' as before; no immediate change needed, but prepare for removal in v5.","message":"The '--pkgfile' CLI argument is deprecated in favor of '--pkgfile' alias (same name, but new validation rules).","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Ensure the full tarball is piped; use 'cat' or 'curl' with appropriate flags to stream fully.","message":"Using '--tarball -' (stdin) requires the tarball to be complete; piping a partial tarball will cause an error.","severity":"gotcha","affected_versions":"all"},{"fix":"For scoped packages like '@scope/pkg', use the exact full name without escaping: '--allow-dependency @scope/pkg'.","message":"The '--allow-dependencies' option does not support scoped packages with slashes unless properly escaped.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Rename the rule in your config and invert the boolean if needed.","message":"Rule 'no-dev-dependencies-in-production' has been deprecated in favor of 'dependencies-in-production' (inverted logic).","severity":"deprecated","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run 'npm install npm-pkg-lint' to add it as a dev dependency.","cause":"Package is not installed or not in node_modules.","error":"Cannot find package 'npm-pkg-lint' from"},{"fix":"Add '\\\"type\\\": \\\"module\\\"' to your package.json or use .mjs extension.","cause":"Running ESM code in a CommonJS environment.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Upgrade Node.js to ^20.18 or >=22.16.","cause":"Node.js 16 is below minimum required version.","error":"Error: Unsupported Node.js version: 16.x"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}