package.json is the standard package configuration management file used in the Javascript world. To call it terrible is an understatement. Here’s why.

  1. No comments - package.json is a JSON file format. JSON format does not support comments by design. So, there is no way to add either precise comments explaining why something is being done in a certain way or design comments explaining the high-level overview of what’s going on.
  2. No command dependencies - Unlike Makefile, there is no way for a command to depend on another command. So, if you decided to create a release without running the command for creating the build first then that’s your fault.
  3. Variable duplication - package.json supports variables. Except it is convoluted enough that only 15 public packages on GitHub use it. So, hard-coded string literals litter all over the place.
  4. No way to reference other commands properly - Any sufficiently complicated package.json references npm explicitly. And that’s wrong. First, it implicitly assumes that one is using npm, second, it implicitly assumes that the npm one is using is the one that’s in the path. Both of these assumptions start to fail once you have a million users using your library.
  5. Stringification - Like the rest of Javascript, package.json suffers from stringification. While the JSON format supports booleans, integers, strings, arrays, and maps but since no operations are possible, eventually gets stringified.