shebangs and cmd shimmer documentation

[pinuke]

Problem Statement

"bin" docs (from package.json) lacks details about how the shebang is intended to work with the package manager

Details (context: https://stackoverflow.com/a/65664083/10534510)

"bin" documentation on package.json lacks details about how there is a shebang "wrapper" for windows, and that the shebang can use other interpreters/environments other than node like electron and python. I also believe that the documentation on npx should also talk about how "bin" inside package.json works.:

Potential Solution

Add the details mentioned in the linked stackoverflow question to the docs.

[MylesBorins]

Hey @smartguy1196

I'm having a bit of trouble understanding the exact ask here. What documentation about the shebang is missing and in which specific doc do you think we should add it to?

[pinuke]

https://docs.npmjs.com/cli/v6/configuring-npm/package-json#bin

Please make sure that your file(s) referenced in bin starts with #!/usr/bin/env node, otherwise the scripts are started without the node executable!

• Fails to mention that this is optional
• Fails to mention that you can replace node with any run time environment such as the one implemented here:
• • https://github.com/joshwnj/electron-start/blob/7a4d7bccb8801d54b31fee34da7fe627f08327e5/bin/start.js#L1
• Fails to mention that this shebang works on windows due to the shebang-to-cmd-file shimmer that npm's packager uses:
• • https://github.com/npm/cmd-shim/blob/f59af911f1373239a7537072641d55ff882c3701/index.js#L22
• • important note: windows does not natively process shebangs. Windows decides what interpreter to use to process a file based off of the file extensionm. On POSIX systems, the file extension is secondary to the shebang. If a POSIX file has a .js extension, but has a #!/usr/bin/env python shebang, the system will start the script in python instead of nodejs. The shebang-to- cmd shimmer reproduces the behavior on windows, for cross-platform uniformity for npx and npm-init

[MylesBorins]

Thanks for the detailed response... I'll follow up with the team next week to see if there is something actionable we can do in the docs

[MylesBorins]

The documentation is now open sourced at https://github.com/npm/documentation if this is still a problem please create an issue on that repo