JoshuaKGoldbergeslint-plugin-package-json
Rules for consistent, readable, and valid package.json files. ๐๏ธ
Installation
This package requires ESLint >=8:
npm install eslint eslint-plugin-package-json --save-devUsage
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";
export default [
// your other ESLint configurations
packageJson.configs.recommended,
];If you want to override the recommended rules:
// eslint.config.ts
import packageJson from "eslint-plugin-package-json";
export default [
// your other ESLint configurations
packageJson.configs.recommended,
{
rules: {
"package-json/valid-package-definition": "off",
},
},
];See ESLint's Configuration Files guide for details on how to customize your rules and other config settings.
Recommended Config for Publishable Packages
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";
export default [
// your other ESLint configurations
packageJson.configs["recommended-publishable"],
];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";
export default [
// your other ESLint configurations
packageJson.configs.recommended, // or packageJson.configs["recommended-publishable"]
packageJson.configs.stylistic,
];Legacy Recommended Config (deprecated)
Usage with ESLint's legacy ("eslintrc") format requires also installing jsonc-eslint-parser:
npm install jsonc-eslint-parser --save-devAdd an override to your ESLint configuration file that specifies jsonc-eslint-parser, this plugin, and its recommended rules for your package.json file:
module.exports = {
overrides: [
{
extends: ["plugin:package-json/legacy-recommended"],
files: ["package.json"],
parser: "jsonc-eslint-parser",
},
],
};You may also want to individually configure rules. See ESLint's Configure Rules guide for details on how to customize your rules.
module.exports = {
overrides: [
{
extends: ["plugin:package-json/legacy-recommended"],
files: ["package.json"],
parser: "jsonc-eslint-parser",
rules: {
"package-json/valid-package-definition": "error",
},
},
],
};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";
export default {
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:
falseforrequire-nameandrequire-version.truefor every otherrequire-*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.
Usage Alongside Prettier
prettier-plugin-packagejson is a Prettier plugin that enforces the same package.json keys ordering as the order-properties and sort-collections rules with default options.
We recommend using both the Prettier plugin and eslint-plugin-package-json's recommended configuration.
The default settings don't conflict, and Prettier plugins can quickly fix up ordering in your editor on save and/or as a Git hook.
Supported Rules
๐ผ Configurations enabled in.\
โ๏ธ Set in the legacy-recommended configuration.\
โ
Set in the recommended configuration.\
๐ฆ Set in the recommended-publishable configuration.\
๐จ Set in the stylistic configuration.\
๐ง Automatically fixable by the --fix CLI option.\
๐ก Manually fixable by editor suggestions.\
โ Deprecated.
| Name | Description | ๐ผ | ๐ง | ๐ก | โ |
|---|---|---|---|---|---|
| bin-name-casing | Enforce that names for bin properties are in kebab case. | ๐จ | ๐ก | ||
| exports-subpaths-style | Enforce consistent format for the exports field (implicit or explicit subpaths). | ๐จ | ๐ง | ||
| no-empty-fields | Reports on unnecessary empty arrays and objects. | โ๏ธ โ ๐ฆ | ๐ก | ||
| no-redundant-files | Prevents adding unnecessary / redundant files. | โ๏ธ โ ๐ฆ | ๐ก | ||
| no-redundant-publishConfig | Warns when publishConfig.access is used in unscoped packages. | โ๏ธ โ ๐ฆ | ๐ก | ||
| order-properties | Package properties must be declared in standard order | โ๏ธ โ ๐ฆ | ๐ง | ||
| repository-shorthand | Enforce either object or shorthand declaration for repository. | โ๏ธ โ ๐ฆ | ๐ง | ||
| require-attribution | Ensures that proper attribution is included, requiring that either author or contributors is defined, and that if contributors is present, it should include at least one contributor. |
๐ฆ | ๐ก | ||
| require-author | Requires the author property to be present. |
||||
| require-bugs | Requires the bugs property to be present. |
||||
| require-bundleDependencies | Requires the bundleDependencies property to be present. |
||||
| require-dependencies | Requires the dependencies property to be present. |
||||
| require-description | Requires the description property to be present. |
โ๏ธ โ ๐ฆ | |||
| require-devDependencies | Requires the devDependencies property to be present. |
||||
| require-engines | Requires the engines property to be present. |
||||
| require-exports | Requires the exports property to be present. |
๐ฆ | |||
| require-files | Requires the files property to be present. |
๐ฆ | |||
| require-keywords | Requires the keywords property to be present. |
||||
| require-license | Requires the license property to be present. |
โ๏ธ โ ๐ฆ | |||
| require-name | Requires the name property to be present. |
โ๏ธ โ ๐ฆ | |||
| require-optionalDependencies | Requires the optionalDependencies property to be present. |
||||
| require-peerDependencies | Requires the peerDependencies property to be present. |
||||
| require-sideEffects | Requires the sideEffects property to be present. |
๐ฆ | |||
| require-type | Requires the type property to be present. |
โ๏ธ โ ๐ฆ | |||
| require-types | Requires the types property to be present. |
||||
| require-version | Requires the version property to be present. |
โ๏ธ โ ๐ฆ | |||
| restrict-dependency-ranges | Restricts the range of dependencies to allow or disallow specific types of ranges. | ๐ก | |||
| restrict-private-properties | Disallows unnecessary properties in private packages. | ๐ง | ๐ก | ||
| scripts-name-casing | Enforce that names for scripts are in kebab case (optionally separated by colons). |
๐จ | ๐ก | ||
| sort-collections | Selected collections must be in a consistent order (lexicographical for most; lifecycle-aware for scripts). | โ๏ธ โ ๐ฆ | ๐ง | ||
| specify-peers-locally | Requires that all peer dependencies are also declared as dev dependencies | โ๏ธ โ ๐ฆ | ๐ก | ||
| unique-dependencies | Checks a dependency isn't specified more than once (i.e. in dependencies and devDependencies) |
โ๏ธ โ ๐ฆ | ๐ก | ||
| valid-author | Enforce that the author property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-bin | Enforce that the bin property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-bundleDependencies | Enforce that the bundleDependencies (also: bundledDependencies) property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-config | Enforce that the config property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-contributors | Enforce that the contributors property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-cpu | Enforce that the cpu property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-dependencies | Enforce that the dependencies property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-description | Enforce that the description property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-devDependencies | Enforce that the devDependencies property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-directories | Enforce that the directories property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-engines | Enforce that the engines property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-exports | Enforce that the exports property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-files | Enforce that the files property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-homepage | Enforce that the homepage property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-keywords | Enforce that the keywords property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-license | Enforce that the license property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-local-dependency | Checks existence of local dependencies in the package.json | โ | |||
| valid-main | Enforce that the main property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-man | Enforce that the man property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-name | Enforce that package names are valid npm package names | โ๏ธ โ ๐ฆ | |||
| valid-optionalDependencies | Enforce that the optionalDependencies property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-os | Enforce that the os property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-package-definition | Enforce that package.json has all properties required by the npm spec | โ | |||
| valid-peerDependencies | Enforce that the peerDependencies property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-private | Enforce that the private property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-publishConfig | Enforce that the publishConfig property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-repository | Enforce that the repository property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-repository-directory | Enforce that if repository directory is specified, it matches the path to the package.json file | โ๏ธ โ ๐ฆ | ๐ก | ||
| valid-scripts | Enforce that the scripts property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-sideEffects | Enforce that the sideEffects property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-type | Enforce that the type property is valid. |
โ๏ธ โ ๐ฆ | |||
| valid-version | Enforce that package versions are valid semver specifiers | โ๏ธ โ ๐ฆ | |||
| valid-workspaces | Enforce that the workspaces property is valid. |
โ๏ธ โ ๐ฆ |
These rules only run on package.json files; they will ignore all other files being linted.
They can lint package.json files at project root and in any subfolder of the project, making this plugin great for monorepos.
Deprecation Policy
We never want to remove things, when we're building them! But the reality is that libraries evolve and deprecations are a fact of life. Following are the different timeframes that we've defined as it relates to deprecating APIs in this project.
RFC Timeframe (6 weeks)
When some aspect of our API is going to be deprecated (and eventually removed), it must initially go through an RFC phase. Whoever's motivating the removal of the api, should create an RFC issue explaining the proposal and inviting feedback from the community. That RFC should remain active for at least 6 weeks. The RFC text should make clear what the target date is for closing the RFC. Once the RFC period is over, if the removal is still moving forward, the API(s) should be officially deprecated.
Removal Timeframe (6 months)
Once an API has been marked as deprecated, it will remain intact for at least 6 months. After 6 months from the date of deprecation, the API is subject to removal.
Development
See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md.
Thanks! ๐
Contributors
Appreciation
Many thanks to @zetlen for creating the initial version and core infrastructure of this package! ๐
๐ This package was templated with
create-typescript-appusing the Bingo engine.