Skip to content

Latest commit

 

History

History
47 lines (27 loc) · 3.39 KB

package-yaml.md

File metadata and controls

47 lines (27 loc) · 3.39 KB
Raw

Native support for package.json5 and package.yaml files

This change allows you to use package.json5 and package.yaml files instead of package.json to describe your package metadata.

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.

Those files will be converted to package.json when package is packed to provide backward compatibility.

Why not just use JSON?

JSON is created to easily parse it in javascript with well-known evil function. Sad but true. It is human-readable, just like XML. But it isn't human-writable so to speak, just like XML.

  1. JSON have no comments, you can't comment out why did you put some dependency, but not the other.
  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.
  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.

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.

A few examples why you should not use package.json:

  • This 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.

  • This is an attempt to put similar comments. Can you guess why it made the package uninstallable?

  • This example shows how an ending comma is bad for version control. And it messes with git blame too! This is how it looks with JSON5, much better.

package.json5/yaml in npm registry

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.

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.

Git repositories on the other hand can be keep clear of all that autogenerated stuff if you update your npm package often enough.

History

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.

Discussions

  1. "package.json should be required to be JSON, and never eval()'ed." - github issue
  2. "*.json config files" - mailing list
  3. "comments in package.json" - mailing list
  4. "Support for ./package.yml ?" - github issue
  5. "Support for comments in package.json" - github issue