Getting Started

💽 Installation

pnpm

pnpm add -D eslint-plugin-package-json

npm

npm install -D eslint-plugin-package-json

yarn

yarn add -D eslint-plugin-package-json

Requirements

• ESLint: >=9.0.0
• Node: ^22.22.2 || >=24.15.0

📖 Configs

Recommended Config

This plugin’s recommended configuration enables its rules on **/package.json files, parsing them with jsonc-eslint-parser.

eslint.config.ts

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

export default defineConfig([
  // your other ESLint configurations
  {
    extends: [packageJson.configs.recommended],
    files: ['package.json'],
  },
]);

If you want to override the recommended rules:

eslint.config.ts

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

export default defineConfig([
  // your other ESLint configurations
  {
    extends: [packageJson.configs.recommended],
    files: ['package.json'],
    rules: {
      'package-json/require-author': 'error',
    },
  },
]);

Tip

See ESLint’s Configuration Files guide for details on how to customize your rules and other config settings.

Recommended Config for Publishable Packages

Note

This config was recently made redundant and is now the same as recommended. However, we’re keeping it as its own config for now, in the event that we add new rules unique to the publishable use case.

The recommended-publishable configuration has everything in it from the standard recommended config, with some additional rules added that are geared towards packages that are intended to be published.

eslint.config.ts

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

export default defineConfig([
  // your other ESLint configurations
  {
    extends: [packageJson.configs['recommended-publishable']],
    files: ['package.json'],
  },
]);

Stylistic Config

The stylistic configuration sets up the parser and files similar to the recommended config, but includes rules that are more opinionated about the style of a package.json. This can be used in addition to the recommended config, or on its own.

eslint.config.ts

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

export default defineConfig([
  // your other ESLint configurations
  {
    extends: [packageJson.configs.recommended, packageJson.configs.stylistic],
    files: ['package.json'],
  },
]);

⚙️ Settings

Some rules can be configured in ESLint shared settings. You can set them in settings.packageJson in an ESLint flat config.

Example:

eslint.config.ts

import packageJson from 'eslint-plugin-package-json';
import { defineConfig } from 'eslint/config';
import * as parserJsonc from 'jsonc-eslint-parser';

export default defineConfig({
  files: ['package.json'],
  languageOptions: {
    parser: parserJsonc,
  },
  plugins: {
    'package-json': packageJson,
  },
  rules: {
    // `description` won't be required in package.json with `"private": true`
    'package-json/require-description': 'error',
  },
  settings: {
    packageJson: {
      enforceForPrivate: false,
    },
  },
});

enforceForPrivate

• Type: boolean
• Default: [see below]

When a package.json file has a "private": true field, it indicates that the package will not be published to npm (or another online registry). Some fields that are nice to have in public packages become less relevant when a package is private. This option determines whether require-* rules, if used, should enforce the presence of the corresponding property in package.json files that have "private": true.

By default, this is:

• false for require-name and require-version.
• true for every other require-* rule.

By specifying this setting as true or false, it will override the defaults and apply the setting for ALL rules. In that case, either all require-* rules will be applied to private packages or no require-* rules will be applied to private packages. Even then, you can override the setting again at the rule level, by using the rule’s ignorePrivate option, which will take precedence over this global setting.

🧪 Experimental API

In addition to the plugin provided in the primary entry point, this package also exports an experimental version of the plugin. The plugin, rules, and configs exported from this entry point are wrapped in a compatibility layer that allows them to be used with the @eslint/json language, instead of the jsonc-eslint-parser parser. In a future major version, we plan to make this the default and only experience, but for now it’s opt-in and exported from the ./experimental entry point.

Caution

All exports from the /experimental entry point are considered unstable and may change in breaking ways in minor version releases.

eslint.config.ts

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

export default defineConfig([
  // your other ESLint configurations
  {
    plugins: {
      json: jsonPlugin, // Needed to use the `json/json` language.
    },
  },
  {
    extends: [packageJson.configs.recommended],
    files: ['package.json'],
  },
]);

Note

You can learn more about our @eslint/json migration plan here.

Isolating Configs

In general, but especially when using multiple languages in ESLint, it’s important to isolate each config object in your eslint.config.ts to apply only to the set of files that you intend it to. The ESLint team recommends including files in every config object for this reason. If you have enabled multiple languages, but have some config objects without any files defined, then those config settings can “leak” in unexpected ways resulting in runtime errors.