eslint-plugin-package-json

Introducing eslint-plugin-package-json

Overview

eslint-plugin-package-json is an innovative tool designed to enhance and maintain consistent, readable, and valid package.json files. In a world where projects are often managed by varying teams and individuals, ensuring standardized configuration files becomes critical. This plugin offers a suite of rules that streamline the validation and organization of package.json files in a project, making maintaining them easier and more efficient.

Installation

The use of eslint-plugin-package-json necessitates a few prerequisites. It is compatible with ESLint, a popular static code analysis tool, and requires version 8 or later. Additionally, it requires the jsonc-eslint-parser. To install these dependencies, add the following packages as development dependencies using npm:

npm install eslint eslint-plugin-package-json jsonc-eslint-parser --save-dev

Usage

Flat Config

eslint-plugin-package-json provides a recommended configuration that can be directly integrated into your ESLint configuration. By doing so, rules are automatically applied to all package.json files:

import packageJson from "eslint-plugin-package-json/configs/recommended";

export default [
	// your other ESLint configurations
	packageJson,
];

For users who need to tailor these rules, customizations can be applied as follows:

import packageJson from "eslint-plugin-package-json/configs/recommended";

export default [
	// your other ESLint configurations
	{
		...packageJson,
		rules: {
			...packageJson.rules,
			"package-json/valid-package-def": "off",
		},
	},
];

Legacy Config

For those using configurations in a more traditional or legacy format, you can include an override in your ESLint configuration file:

module.exports = {
	overrides: [
		{
			extends: ["plugin:package-json/recommended"],
			files: ["package.json"],
			parser: "jsonc-eslint-parser",
			plugins: ["package-json"],
		},
	],
};

With further customization options available:

module.exports = {
	overrides: [
		{
			extends: ["plugin:package-json/recommended"],
			files: ["package.json"],
			parser: "jsonc-eslint-parser",
			plugins: ["package-json"],
			rules: {
				"package-json/valid-package-def": "error",
			},
		},
	],
};

For detailed customization, refer to the ESLint documentation on configuration files and rules.

Integrating with Prettier

prettier-plugin-packagejson works seamlessly alongside eslint-plugin-package-json, ensuring your package.json maintains a precise key order as defined by the order-properties and sort-collections rules. Using both plugins is recommended as there is no conflict between their default settings, and they complement each other well, providing automated fixes either immediately in your editor or within a git hook.

Supported Rules

The plugin introduces several rules that only apply to package.json files:

• order-properties: Enforces properties to appear in a standard order.
• repository-shorthand: Defines how the repository should be declared, either in object or shorthand form.
• sort-collections: Requires entries in collections (dependencies, scripts) to be sorted alphabetically.
• unique-dependencies and valid-local-dependency: Ensure logical integrity and existence of dependencies.
• valid-name and valid-version: Ensures names and versions adhere to npm standards.
• valid-package-def and valid-repository-directory: Checks compliance with npm specifications and correct repository pathing.

These rules are instrumental in ensuring that package.json files are not only error-free but also follow a widely accepted format, which is pivotal in larger projects like monorepos.

Contributors

This project is a collaborative effort maintained by a diverse group of contributors from the development community. Eighteen heralded contributors bring their unique expertise and perspectives, fostering an open-source community united in improving the package.json development experience.

Appreciation

Special thanks are extended to @zetlen for their foundational work on the initial iteration of this package, setting the groundwork for ongoing enhancements and utility in eslint-plugin-package-json.