[BUG] `bin` was converted to an object warnings when using string as `bin`.

[byCedric]

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

In the package.json's bin documentation, it's documented that you can use an object with one or more bin file references OR use a single string.

Unfortunately, this is now marked as "error in your package.json when publishing".

Expected Behavior

I expected this notation to not be marked as an error, as the documentation clearly documents this as a valid option.

Steps To Reproduce

• $ npm init
• Add a bin file
• Configure "bin": "path/to/file.js"
• $ npm publish

Environment

• npm: 10.2.4
• Node: 20.10.0
• OS: MacOS Sonoma 14.2.1
• platform: Macbook Pro (14", 2023)

[wraithgar]

We'll want to update the docs on this. under the hood npm was always silently converting the string to the object form, meaning the packument didn't match the package.json. We're slowly trying to remove those differences, so folks will want to use the full form going forward.

[trivikr]

We'll want to update the docs on this

I think users who have shortform version in thier package.json may like to preserve it because of readability - esp since documentation provided it as a alternative.

under the hood npm was always silently converting the string to the object form

Can npm cli continue to do this without emitting warning?

[wraithgar]

Can npm cli continue to do this without emitting warning?

No, in the future this will not be permitted. Having a package.json file on disk that differs from the manifest in the registry is a security concern.

[mrazauskas]

@wraithgar Thanks for explanation.

Just a detail: paths are starting with ./ in the documentation examples, but ./ gets stripped by auto-correct as well. It felt like ./bin.js and bin.js are equivalent. It is interesting to ask why ./ gets striped? For instance, fields like main are allowed to have path starting with ./.

[arcanis]

folks will want to use the full form going forward.

What measures exactly will you be taking? Will it be enforced by the registry (in which case is there anywhere Yarn can subscribe to be aware of similar changes)? What about packages that are already published with bin being a string (ex)?

under the hood npm was always silently converting the string to the object form, meaning the packument didn't match the package.json

Isn't this discrepancy a npm-specific thing? Why not just not make the translation, rather than deprecate "bin can be a string"?

[wraithgar]

What about packages that are already published with bin

They will continue to be supported, and package managers will likely have to support that form indefinitely.

Will it be enforced by the registry

The enforcement will primarily be that they can't differ. See below for security caveats.

Isn't this discrepancy a npm-specific thing? Why not just not make the translation

Probably yes. npm has been doing this translation a LONG time. The initial choice was to do the smallest change possible, which was to change nothing, and start warning users that the change was even happening.

The next step has not been planned out, but I suspect that SOME form of bin entry validation is going to have to occur. Some of the normalization in https://github.com/npm/npm-normalize-package-bin and now https://github.com/npm/package-json is security related and will not be going away. In those cases I can see a future where the npm registry flat out refuses to accept them. That's not a near future though, as there is a pretty long tail of support for existing package managers.

If you feel you have a good suggestion for where that middle ground lies: i.e. normalizing the security stuff but leaving the rest alone, we'd be very open to that.

TLDR the last thing we want to do is break existing packages, and we want to give folks a LOT of time to get their package.json entries fixed in the event the registry starts enforcing more security filtering.