pretty-package-json

Prettier for package.json.

Overview

I like my package.json files to be nearly organized, making sure that each property is in the same order as listed in the official npm package.json documentation, including nested objects like author, contributors, directories and more.

This tools allows me to stop doing that manually. I just %!pretty-package-json from Vim and call it a day.

Usage

Format given file, stdin or package.json otherwise according to rules, and print it to stdout:

pretty-package-json whatever.json
pretty-package-json < whatever.json
pretty-package-json

Format given file or package.json otherwise, and overwrite it:

pretty-package-json --write whatever.json
pretty-package-json --write

Rules

The top-level keys are sorted as defined in the documentation.

Reveal top-level keys

1. name
2. version
3. description
4. keywords
5. homepage
6. bugs
7. license
8. author
9. contributors
10. funding
11. files
12. main
13. browser
14. bin
15. man
16. directories
17. repository
18. scripts
19. config
20. dependencies
21. devDependencies
22. peerDependencies
23. peerDependenciesMeta
24. bundledDependencies
25. optionalDependencies
26. overrides
27. engines
28. os
29. cpu
30. private
31. publishConfig
32. workspaces

Those are automatically fetched from the documentation. But for nested object keys, there's extra rules that need to be defined manually (see below).

We also support extra keys that are not part of the npm documentation but are commonly used in the ecosystem, like type, module, exports, and types.

Sorting and unknown keys

Anywhere we're sorting according to a predefined order, unknown keys will be added at the end in the same order they were found.

Empty structures

Empty arrays and objects are removed.

Redundant homepage and bugs

If the homepage and bugs match the one that can be derived from the repository by hosted-git-info, the keys will be removed.

For example:

{
  "homepage": "https://github.com/valeriangalliat/pretty-package-json",
  "bugs": "https://github.com/valeriangalliat/pretty-package-json/issues",
  "repository": "valeriangalliat/pretty-package-json"
}

Here the homepage and bugs are redundant and it will be rewritten as:

{
  "repository": "valeriangalliat/pretty-package-json"
}

author and contributors

Converted to the short form name <email> (url) unless peopleFormat is set to object, then it's sorted as:

1. name
2. email
3. url

bin

If contains only a single script matching the package name, it's flattened as a string.

directories

1. bin
2. doc
3. lib
4. man

repository

Convert to the shortest form supported, e.g. use/repo if hosted on GitHub, gitlab:user/repo, a full URL, or otherwise sorted as:

1. type
2. url
3. directory

scripts

Sorted alphabetically unless sortScripts is set to false.

dependencies, devDependencies, peerDependencies and optionalDependencies

Sorted alphabetically like npm does by default when populating those objects.

engines

1. node
2. npm

Extra keys

• $schema: for JSON Schema validation.
• type: Node.js input type, e.g. "type": "module" or "type": "commonjs".
• module: Node.js legacy method that allowed to define the ES module entry point, as opposed to CommonJS in main.
• exports: Node.js field allowing to define hybrid entry points.
• types: TypeScript types.

To confirm this list and see the non-npm top-level keys that were manually added, run:

git diff --no-index npm-keys.json keys.json