🚀 Feature: add a rule to control which extra top-level package.json properties are allowed

[andreww2012]

Feature Request Checklist

• I have searched for related issues and found none that matched my issue.

Overview

package.json allows arbitrary properties which are often used by other tools, such as prettier, lint-staged or pnpm. Some people prefer to consolidate different tools' settings in one place as much as possible to avoid creating a multitude of configuration files in the root of the repo - while others may prefer the opposite.

I have two use cases for which I would like a rule that can restrict certain top-level properties in package.json:

• The first case (described above): I prefer to keep my package.json as minimal and clean as possible, since tools' options sometimes can be long and/or unrepresentable in JSON;
• The second case: older versions of pnpm used the pnpm package.json key for pnpm specific options. Nowadays, the recommended way is to use a separate pnpm-workspace.yaml file, while the former method continues to work. It'd be nice to disallow pnpm property in that scenario.

Proposed rule name

restrict-top-level-properties

Proposed options

type Options = [{
  ban?: (string | {property: string; message?: string})[]; // Alternative option: Record<string, true | string>
}];

ban

Provides a list of banned top-level properties with an optional custom message shown in the error message when the banned property is used. Can include any property, even standard ones like name or version. If the same property is banned multiple times, the last declaration takes precedence. (Alternatively, ban could be represented as Record<string, true | string> where a string value represents a custom message.)

Dropped from this issue

allow

• If omitted: all properties are allowed except those listed in ban.
• If an empty array: no extra top-level properties are allowed (only standard package.json fields).
• If a non-empty array: only the listed extra properties are allowed in addition to the standard fields.

ban can still be used alongside with allow to provide a custom message for specific properties.

If the same property appears in both allow and ban, the rule should throw an error.

[michaelfaith]

Thanks for the idea! I think I'm on board with the behavior of the ban option.

Alternatively, ban could be represented as Record<string, true | string> where a string value represents a custom message

I like your original type proposal more, since it aligns well with some other well-known rules (e.g. no-restricted-imports). So, that makes sense to me.

I'm not as on board (yet) with the allow option. Mainly because of the "standard fields" piece. I understand why that's part of the proposal, since it would be tedious to have to add every property to an allow list, but I see a few problems with introducing this concept.

1. It adds a level of ambiguity to how the rule works. Different package managers may have different sets of "standard" fields. So, which ones do we consider standard? If it's only npm then we're now excluding a non-trivial segment of the community with this function.
2. Due to the above, I can see this being a big source of confusion for people. "Is a property a standard field or not a standard field?". They now have to know the difference between those things in order to reason about the rule, and that's not great from a DX perspective.
3. In both the case where we only support npm fields with this, and the case where we support all package managers, it's a maintenance issue. Keeping that list up to date as these tools change, is going to be hard to maintain over time.

So, I'm not quite there with the allow option side of this proposal. I don't know of a great way to do that well. If we pull out the standard field concept, then it becomes more tedious for the user to add everything they want to allow, and if we include it, then it has all these issues. Unless you can think of a better way to support that feature, I'd recommend dropping it.

[andreww2012]

1. I propose leveraging package-manager-detector, and based on the detected PM, treat different fields "standard".
2. This behavior and the "standard fields" list can be documented.
3. While this is technically a maintenance concern, new fields are rarely introduced. Even if that happens:
   • A new field is unlikely to see widespread usage immediately;
   • It can always be added to the allow list.

Based on my research, here is the list of package managers' supported fields:

Commonly supported

packageManager

author
bin
bugs
config
contributors
cpu
dependencies
description
devDependencies
engines
exports
files
homepage
keywords
license
main
man
name
optionalDependencies
os
peerDependencies
peerDependenciesMeta
private
publishConfig
repository
scripts
version

PM specific

Field name	npm	pnpm	yarn@1	yarn berry	bun
browser	✅	❌	❌	✅	✅
bundleDependencies	✅	✅	✅	❌	✅
bundledDependencies	✅	✅	✅	❌	✅
dependenciesMeta	❌	✅	❌	✅	❌
devEngines	✅	✅	❌	❌	❌
directories	✅	✅	✅	❌	❓
funding	✅	✅	❌	❌	❌
installConfig	❌	❌	❌	✅	❌
languageName	❌	❌	❌	✅	❌
libc	✅	✅	❌	✅	❌
man	✅	✅	✅	❓	❓
overrides	✅	❌	❌	❌	✅
pnpm	❌	✅	❌	❌	❌
preferUnplugged	❌	❌	❌	✅	❌
resolutions	❌	❌	✅	✅	❌
stableVersion	❌	❌	❌	✅	❌
trustedDependencies	❌	❌	❌	❌	✅
workspaces	✅	❌	✅	✅	✅

Sources:

• https://docs.npmjs.com/cli/v11/configuring-npm/package-json
• https://pnpm.io/10.x/package_json
• https://pnpm.io/9.x/package_json
• https://github.com/pnpm/pnpm/blob/05fb1aee5f6c40fb876564ece90b04174a327e12/packages/types/src/package.ts#L82
• https://classic.yarnpkg.com/lang/en/docs/package-json/
• https://yarnpkg.com/configuration/manifest
• https://bun.com/docs/pm/cli/install

[andreww2012]

Actually, I think we shouldn't give this rule the responsibility to effectively "check if the field makes sense with your package manager". (It might be reasonable to create a separate rule dedicated specifically to that). Moreover, this will only work if allow option is provided.

Therefore, I believe all the above fields should be treated as "standard".

[michaelfaith]

I appreciate the additional research, but it doesn't really address the prime concerns I have:

• it still creates a maintenance burden for us to keep on top of every package manager's "standard" fields
• introduces new concerns that we haven't had before (e.g. how long do we consider pnpm v9 only fields as "standard"...?).
• there's inherent ambiguity for the users who now have to consult the long list of fields in our docs, just to use the rule

I'm a big fan of starting small. And since we're at least aligned on the ban side of this new rule idea, i would propose that we start with that and then can consider the allow feature as a possible follow-up, if we can end up ironing out the problems? Unless you think that's an essential part of the rule?

[andreww2012]

The allow option is not strictly essential, but it is still an important part of the rule. I am therefore fine with progressing iteratively and starting by implementing only the ban option 🙂

---

I think the main intent of this option is saying "hey, please use a separate config file for whatever tool instead of inlining it in package.json". If a field is known to be recognized by one of the well-known package managers, we should allow it regardless of which package manager is actually used, since such a field is unlikely to be consumed by some unrelated tool.

Based on that, I propose maintaining a single list of all known package-manager-specific properties. I do not expect this list to change often, since new properties are introduced relatively infrequently.

how long do we consider pnpm v9 only fields as "standard"

I have been thinking about this as well, and I believe such fields should be recognized as standard as long as the version(s) that support them are not considered "dead" (i.e. officially deprecated, little used, etc.).

[michaelfaith]

Updated the OP to remove allow from this issue (moved to an expand panel), and marked as "accepting PRs".

I think the main intent of this option is saying "hey, please use a separate config file for whatever tool instead of inlining it in package.json".

I understand the intent, but I don't think it's something we should maintain and have to stay on top of for all package managers.

I am therefore fine with progressing iteratively and starting by...

Just to be clear, there is no guarantee that allow will make it in. That's not to say it won't, but I just want to be clear in the expectations. At this point, I'm not convinced it's worth the cost to maintain. Feel free to open a new issue after the base implementation lands to discuss that part of it further.