-
Notifications
You must be signed in to change notification settings - Fork 3k
Support for comments in package.json #4482
Comments
It was javascript three years ago, look at #408. Sadly it was removed. Anyway, javascript doesn't really fit here because ideally npm should not be executing any code at install time. But we can use YAML or JSON5 instead, they are both support comments and have much nicer syntax, I tried this approach with my packages for half a year now. I'm currently seriously thinking about forking npm to add this support. Not sure how it'll go in the future, but I'll be more than happy to make a pull request against npm if somebody with nickname starting with "i" changes his mind. But until then can you try yapm to see if it works? |
I'd love to use yapm, but it's a real fork of npm and I don't know for how long you will keep it up-to-date. I created a pre-npm hook 2 years ago but apparently it doesn't work anymore: https:/saschagehlich/npm-yaml |
Yeah, this is not happening. You can always use {
"//": "a comment",
"//": "another comment"
} |
Can you also describe WHY it is not happening? |
There is a simple wrapper, versions [email protected] and less. I moved to a "real fork" only a month ago, and not convinced it's a right path. Also, I asked to introduce npm plugins in #4416, but got negative response straight up. Any other suggestions? Anyone? |
@domenic Your solution does not work.
|
Notice my comments were at top level. |
Yeah, the keys in the |
@domenic: The refusal to implement support for comments, or an alternative format like JSON5, is most unfortunate. There are official efforts to use npm for front-end packaging (http://blog.npmjs.org/post/101775448305/npm-and-front-end-packaging) and unofficial ones to show how npm is often sufficient instead of grunt or gulp (@keithamus's How to Use npm as a Build Tool). All these efforts are annoyingly limited by a format that doesn't allow comments or multi-line strings. By comparison the Please reconsider a mechanism to allow comments in package.json. |
Don't forget it isn't just npm that reads the package.json file, Node's module system also does. It's one (massive, unwieldy, big breaking) change for npm to support this, but a whole new level of pain for Node to also. Supporting comments means using a different JSON parser, which means it'll probably be slower, which means it'll never get picked up by Node, which means it should never be picked up by npm. As much as I'd welcome comments in JSON, I can very much understand and accept why it's probably never going to happen. Ho hum, there's lots of other places to document stuff, README.md, js files, etc. |
So what kind of commentary are you hoping to add? |
Well, it shouldn't. But it doesn't matter here 'cause node module system doesn't fail if package.json can't be parsed. And since only thing node needs is "main" field which can be replaced with "index.js", I'm perfectly fine with node module system failing to read those.
This kind - that's bunyan wannabe comments I usually refer to. Also, this kind (there are a lot of comments there) - that's my comments, I'm using them liberally since I switched to YAML format. Comments about which packages are deprecated and why. Comments about which packages are using semver and which don't. And so on and so forth. |
TODO comments are another type. E.g. "TODO rm this dep once XYZ is in place." |
This is a bummer for me as well. In my application I have at least one dependency pegged to a specific version because the latest version has unresolved issues. It'd be nice to communicate in the natural place to my team (and myself in the future) that this was intentional and why it was done. |
This is a great example of documenting your package.json outside of the JSON - comments would not be as thorough as this. |
@keithamus while thorough documentation is nice, there's virtues to brevity and locality too. A short comment next to the relevant line of |
This seems a bit of an ugly hack, but passing |
For maintaining larger projects, I’ve found comments to be very important. It’s probably too big a change, but Node’s |
I use blank lines and grouping to make this manageable - e.g. blank line before Different solution, but same aim, I'd like it if npm would recurse dependency objects so you could group them, e.g.: https://twitter.com/jbscript/status/654653797407457280 |
If I like to generally consider this file as a binary file: not intended to be read or modified by anything but tools (more likely |
I agree that comments in package.json would be nice. Our team has used the |
+1 @josiahsprague. |
I would absolutely thrilled to see an alternative |
Totally agree. I hope that the maintainers of npm will see how useful comments can be in package.json (and .json config files in general). |
Actually, leave it to Crock to remind us why we shouldn't do this. The running answer is: "Put all the comments you want in there. Just run it through a parser before you distribute it." https://plus.google.com/+DouglasCrockfordEsq/posts/RK8qyGVaGSr Good comments here And I can't disagree with the comments made here: |
Ok so what if npm piped |
Can that be handled via a |
How would you deal with commands like |
@mathieumg You're absolutely right. That's the case I keep forgetting about, and I have no idea how to handle it properly. npm would have to be able to both read the file with and comments and write it back out, preserving the comments. |
https:/rlidwka/jju handles that scenario correctly! |
Since NPM's package.json mostly conforms to the CommonJS 1.1 spec, it's possible to be creative here. http://stackoverflow.com/a/27232456/398574 |
And https:/kof/node-xpkg#x-packagejson5 does exactly this. That |
How would that fare with the scenario I described above? |
JSON5 supports comments. You could put them in your package.json and then pipe the file through https:/kof/node-xpkg#x-packagejson5 |
I'm referring to the |
http://eslint.org/docs/user-guide/configuring#comments-in-configuration-files |
package.json is one of the reasons why Human JSON exists. |
The hack of "//": "comment" will not work in a list of dependencies. How about just special casing this? That is, no package dependency named "//" will be allowed and the line will be ignored? |
Please make http://json5.org/ possible. A format without comments is not feasable for human-written configuration files imho. Or is there some automated way to convert to a comment-free package.json while running npm install (e.g. using the frontend-maven-plugin )? |
+1 for json5. The larger that package.json gets the more difficult it is to keep track of why specific things were added. |
I would add that a lot of tools now support configuration from within package.json, and it would be convenient to be able to // some line while debugging or add explanations for them. |
Wondering what flavor of JSON Sublime Text and Visual Studio Code use for their config. They both allow comments. |
This is highly unlikely to ever change in npm itself. As #408 hints, having an executable manifest leads to whole classes of security flaws (and the complexity of YAML has, in reality, caused problems for the Ruby world for this reason). As #3336 hints, and as many comments on this issue explicitly say, there's nothing preventing you from creating a different representation of the metadata in Because this is unlikely to change, further bikeshedding is unlikely to be productive. Therefore, I'm locking this issue. |
I know that there are no comments allowed in JSON, but I'm running a product that has 30+ dependencies, so package.json gets very large and unclear.
Are there any solutions for that? A
package.js
file that exports a hash would be a solution but it could also contain executable code.The text was updated successfully, but these errors were encountered: