This repository has been archived by the owner. It is now read-only.
Self-documented scripts in package.json #18515
Open
Comments
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
What's the feature?
NPM could handle either an object or a string for each script in
package.json
. It would give you the ability to document the scripts, like this:Then the description could be displayed when running the script:
Here is a kind of a specification for the script object:
scripts
key must be a string or an object value.value
(better name suggestions are welcome) of type string that contains the runnable commanddescription
of type string or array of string (multiline comment) that contains a human-readable description of the script.What problem is the feature intended to solve?
The JSON format doesn't allow comments. The need of comments is often the result of bad code or poor design, but when using the NPM scripts as the build tool, it could easily lead to a dozen of mono-line obscur shell commands that nothing can make easier to read.
I found this interesting email from @isaacs on the mailing list:
https://groups.google.com/forum/#!msg/nodejs/NmL7jdeuw0M/yTqI05DRQrIJ
It makes clear that:
"//"
will never be used by NPM so users can use it to add comments inpackage.json
The
"//"
workaround is no longer acceptable because NPM5 automatically removes duplicate keys so:becomes
after any NPM command.
That's why I'm coming with this handy, pure JSON, way to document user scripts.
Is the absence of this feature blocking you or your team? If so, how?
I can't honestly say it's "blocking". Some workarounds exist like externalizing the commands in shell scripts (it hurts the DRY principle though).
Let's say it's nice to have.
Is this feature similar to an existing feature in another tool?
As far as I know, other platforms generally support comments in their project descriptor:
Is this a feature you're prepared to implement, with support from the npm CLI team?
Yes, definitely.
The text was updated successfully, but these errors were encountered: