| 1 | Native support for package.json5 and package.yaml files
|
| 2 | -------------------------------------------------------
|
| 3 |
|
| 4 | This change allows you to use `package.json5` and `package.yaml` files instead of `package.json` to describe your package metadata.
|
| 5 |
|
| 6 | All npm features (including `npm version` and `--save`) will work with `package.json5` out of the box (with YAML it's trickier, patches welcome), so you basically will never have to deal with JSON in development.
|
| 7 |
|
| 8 | Those files will be converted to `package.json` when package is packed to provide backward compatibility.
|
| 9 |
|
| 10 | ### Why not just use JSON?
|
| 11 |
|
| 12 | JSON is created to easily parse it in javascript with well-known ev**i**l function. Sad but true. It is human-readable, just like XML. But it isn't human-writable so to speak, just like XML.
|
| 13 |
|
| 14 | 1. JSON have no comments, you can't comment out why did you put some dependency, but not the other.
|
| 15 | 2. JSON have no trailing comma. So you can't easily remove an item, add an item or interchange two arbitrary lines in a list.
|
| 16 | 3. JSON require ugly enquoting both keys and values in object. JSON5 requires enquoting values only, and YAML doesn't require quotes in most cases.
|
| 17 |
|
| 18 | Guys, seriously, JSON is designed to be written by computers, not humans. Humans could read it easily, but maintaining JSON is a pain. Don't do it.
|
| 19 |
|
| 20 | #### A few examples why you should not use package.json:
|
| 21 |
|
| 22 | - [This](https://github.com/trentm/node-bunyan/blob/03228323268af488d6261bf9feee2eb16826f777/package.json#L20) is a classic example how to place comments in JSON file. There is nothing wrong with it (except for syntax highlighting), but it looks ugly.
|
| 23 |
|
| 24 | - [This](https://github.com/jwarkentin/node-monkey/blob/083a7623f5932ec01b913c564c328f7d4d789885/package.json#L29) is an attempt to put similar comments. Can you guess why it made the package uninstallable?
|
| 25 |
|
| 26 | - [This](https://github.com/npm/npm/commit/20439b21e103f6c1e8dcf2938ebaffce394bf23d#diff-6) example shows how an ending comma is bad for version control. And it messes with `git blame` too! [This](https://github.com/rlidwka/yapm/commit/5fa65e5bddc4e4c555cc7f2fb47457c2978dd1bd#diff-8) is how it looks with JSON5, much better.
|
| 27 |
|
| 28 | ### package.json5/yaml in npm registry
|
| 29 |
|
| 30 | `package.json` will be created before packing/publishing a package to the npm registry. It is technically possible to avoid doing it, but to ensure interoperability we must compile this file.
|
| 31 |
|
| 32 | By the way, the same thing goes for coffee-script guys. There's nothing wrong with using .coffee files in development, but they should be compiled before publishing.
|
| 33 |
|
| 34 | Git repositories on the other hand can be keep clear of all that autogenerated stuff if you update your npm package often enough.
|
| 35 |
|
| 36 | ### History
|
| 37 |
|
| 38 | This feature was the reason why yapm exists in the first place. YAML support added in May 2013 (under the name "ynpm" at that time), and JSON5 support was added in version 0.7.0 in December 2013.
|
| 39 |
|
| 40 | ### Discussions
|
| 41 |
|
| 42 | 1. "package.json should be required to be JSON, and never eval()'ed." - [github issue](https://github.com/isaacs/npm/issues/408)
|
| 43 | 2. "\*.json config files" - [mailing list](https://groups.google.com/forum/?fromgroups#!topic/nodejs/WVNeUlcWUDg)
|
| 44 | 3. "comments in package.json" - [mailing list](https://groups.google.com/forum/?fromgroups#!topic/nodejs/NmL7jdeuw0M)
|
| 45 | 4. "Support for ./package.yml ?" - [github issue](https://github.com/isaacs/npm/issues/3336)
|
| 46 | 5. "Support for comments in package.json" - [github issue](https://github.com/npm/npm/issues/4482)
|
| 47 |
|