eslint-package-json

Powerful ESLint rules for package.json

Lint and autofix your package.json files with ESLint, powered by @eslint/json.

This plugin catches real package.json mistakes (invalid names, bad version ranges, broken exports, misplaced @types/*, redundant files entries, and more) and fixes many of them automatically.

Install

npm install --save-dev eslint eslint-package-json

Requires ESLint >=10.4, flat config, and ESM.

Usage

Add the recommended config to your eslint.config.js:

import {defineConfig} from 'eslint/config';
import packageJson from 'eslint-package-json';

export default defineConfig({
	files: ['**/package.json'],
	plugins: {
		'package-json': packageJson
	},
	extends: [
		'package-json/recommended'
	]
});

This lints every package.json in your project. To tweak individual rules, add them to the same config object:

import {defineConfig} from 'eslint/config';
import packageJson from 'eslint-package-json';

export default defineConfig({
	files: ['**/package.json'],
	plugins: {
		'package-json': packageJson
	},
	extends: [
		'package-json/recommended'
	],
	rules: {
		'package-json/dependency-version-range': [
			'error',
			{
				range: 'caret'
			}
		]
	}
});

If you prefer to wire it up manually instead of using a preset:

import json from '@eslint/json';
import {defineConfig} from 'eslint/config';
import packageJson from 'eslint-package-json';

export default defineConfig({
	files: ['**/package.json'],
	language: 'json/json',
	plugins: {
		json,
		'package-json': packageJson
	},
	rules: {
		'package-json/valid-fields': 'error'
	}
});

Configs

• recommended — Enables the rules that catch real, uncontroversial mistakes.
• all — Enables every rule. Useful for discovering rules; not recommended for everyday use.

Rules

💼 Configurations enabled in.
✅ Set in the recommended configuration.
🔧 Automatically fixable by the --fix CLI option.
💡 Manually fixable by editor suggestions.

| Name                                       | Description | 💼 | 🔧 | 💡 | | :----------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------- | :- | :- | :- | | consistent-name-casing | Enforce kebab-case for keys in scripts and bin objects. | | | | | consistent-path-prefix | Enforce consistent ./ prefix on local path fields. | ✅ | 🔧 | | | dependency-version-range | Enforce a consistent version range style for dependencies. | ✅ | | 💡 | | description-format | Enforce formatting of the description field. | | 🔧 | | | no-absolute-paths | Disallow absolute paths in path fields. | ✅ | | 💡 | | no-backslash-paths | Enforce forward slashes in path fields. | ✅ | 🔧 | | | no-core-module-dependencies | Disallow dependencies that shadow Node.js built-in modules. | ✅ | | 💡 | | no-deprecated-fields | Disallow fields and scripts that npm has deprecated. | ✅ | | | | no-dist-tag-dependencies | Disallow dist-tags as dependency specifiers. | ✅ | | | | no-duplicate-dependencies | Disallow a dependency listed in multiple dependency groups. | ✅ | 🔧 | 💡 | | no-empty-fields | Disallow empty fields. | ✅ | | 💡 | | no-exact-peer-dependencies | Disallow exact versions for peer dependencies. | | | 💡 | | no-exports-trailing-slash | Disallow trailing-slash folder mappings in exports/imports. | ✅ | 🔧 | | | no-fallback-export-arrays | Discourage string-target fallback arrays in exports/imports. | ✅ | | | | no-git-dependencies | Disallow git URLs as dependency specifiers. | | | | | no-http-dependencies | Disallow HTTP URLs as dependency specifiers. | ✅ | | | | no-install-scripts | Disallow install lifecycle scripts. | ✅ | | 💡 | | no-invalid-direct-overrides | Disallow npm overrides that conflict with direct dependencies. | ✅ | 🔧 | | | no-local-dependencies | Disallow local filesystem paths as dependency specifiers. | | | | | no-manual-maintainers | Disallow a manually-set maintainers field. | ✅ | | 💡 | | no-missing-files | Disallow missing files referenced by package metadata. | | | | | no-nested-exports | Disallow exports and imports in nested package.json files. | ✅ | | 💡 | | no-orphan-script-hooks | Disallow pre/post script hooks without a corresponding script. | ✅ | | | | no-orphan-types | Disallow @types/* packages without a corresponding dependency. | ✅ | | 💡 | | no-overrides-in-published-package | Disallow overrides in packages that can be published. | ✅ | | 💡 | | no-package-manager-engines | Disallow package manager versions in the engines field. | ✅ | | 💡 | | no-pre-release-dependencies | Disallow pre-release versions as dependency specifiers. | | | | | no-redundant-files | Disallow redundant entries in the files field. | ✅ | 🔧 | | | no-redundant-repository-fields | Disallow bugs/homepage values that duplicate what npm infers from repository. | | 🔧 | | | no-restricted-dependencies | Disallow specific dependencies. | | | | | no-restricted-fields | Disallow specific fields. | | | 💡 | | no-self-dependency | Disallow a package depending on itself. | ✅ | | 💡 | | no-typo-fields | Disallow misspelled package.json field names. | ✅ | 🔧 | | | no-wildcard-dependencies | Disallow wildcard version ranges for dependencies. | ✅ | | | | no-workspace-protocol-in-published-package | Disallow workspace: dependency specifiers in packages that can be published. | ✅ | | | | peer-dependencies-as-dev-dependencies | Enforce peer dependencies to also be listed in devDependencies at a compatible version. | ✅ | | 💡 | | prefer-engines-range | Prefer open-ended >= ranges in the engines field. | ✅ | | 💡 | | prefer-exports | Prefer an exports-first package interface. | ✅ | | | | prefer-files-field | Require a files allowlist that covers published entry points. | ✅ | | | | prefer-https-urls | Prefer https:// URLs in metadata fields. | ✅ | 🔧 | | | prefer-provenance | Enforce npm provenance via publishConfig.provenance. | | | 💡 | | prefer-shorthand | Prefer the shorthand string form of fields where possible. | ✅ | 🔧 | | | prefer-side-effects-field | Recommend declaring the sideEffects field for packages. | ✅ | | 💡 | | prefer-type-module | Prefer the type field to be module. | ✅ | | 💡 | | require-bin-shebang | Require bin files to start with the exact #!/usr/bin/env node shebang. | ✅ | | | | require-default-condition | Require a last default entry in exports/imports conditions objects. | ✅ | | | | require-engines | Require the engines.node field. | ✅ | | | | require-entry-point | Require an entry point field. | ✅ | | | | require-exports-root | Require a usable . root entry in the exports field. | | | | | require-fields | Require specific fields to be present, always or only for published packages. | ✅ | | | | require-private | Require the private field to be true. | | | 💡 | | require-private-when-workspaces | Require private when workspaces is set. | ✅ | | 💡 | | require-types-in-exports | Require correctly ordered and module-compatible types in exports. | ✅ | | | | restrict-fields-when-private | Disallow fields that have no effect when the package is private. | | | 💡 | | sort-dependencies | Enforce alphabetical ordering of dependencies. | ✅ | 🔧 | | | sort-files | Enforce a canonical order for entries in the files field. | ✅ | 🔧 | | | sort-properties | Enforce a canonical order for top-level package.json fields. | ✅ | 🔧 | | | sort-scripts | Enforce alphabetical ordering of scripts. | | 🔧 | | | types-in-dev-dependencies | Enforce @types/* packages to be in devDependencies. | | | 💡 | | valid-fields | Enforce valid values for package.json fields. | ✅ | 🔧 | 💡 |

FAQ

How is this different from eslint-plugin-package-json?

Both lint package.json through ESLint, and eslint-plugin-package-json is a great project. I built this because I wanted a different design:

• Fewer, more powerful rules. Instead of dozens of near-identical rules (one per field, one per dependency group), I use a handful of rules with options. For example, one dependency-version-range rule with a dependencyTypes option replaces a whole family of no-caret-* / prefer-tilde-* rules. Less to learn, less to configure.
• Native @eslint/json. I target ESLint's official JSON language directly, with no parser compatibility layer.
• Autofix-first. Every rule that can safely fix or suggest a fix does.

Why not npm-package-json-lint?

It's a separate CLI with its own config format and no autofix. This plugin lives inside ESLint, so it shares your editor integration, --fix, and flat config.

How do I disable a rule for package.json?

package.json must be valid JSON, so it cannot contain comments.

Disable the rule in eslint.config.js instead:

import {defineConfig} from 'eslint/config';
import packageJson from 'eslint-package-json';

export default defineConfig({
	files: ['**/package.json'],
	plugins: {
		'package-json': packageJson
	},
	extends: [
		'package-json/recommended'
	],
	rules: {
		'package-json/no-orphan-types': 'off',
	},
});

Use a more specific files pattern when the rule should be disabled for only one package.

Related

• eslint-plugin-unicorn — Lots of awesome ESLint rules.
• eslint-node-test — ESLint rules for the Node.js built-in test runner.