Command line app to deep sort JSON files, retains package.json special key order


the idea of json-sort-cli

Use it

Once installed, either call jsonsort or sortjson with file name, folder name or a list thereof, with or without flags:

$ jsonsort file1.json "folder1/folder2/**/*.*" folder3 -s
$ jsonsort * -t -n -s
$ jsonsort yourspecialfolder -s

$ jsonsort -v
$ jsonsort --version
$ jsonsort -h
$ jsonsort --help

or sortjson, same thing. We wired up both. See the API section (of call for help via CLI, jsonsort -h).

API - flags

short long description
-n --nodemodules Don't ignore any node_modules folders and package-lock.json's
-t --tabs Use tabs for JSON file indentation
-i --indentationCount How many spaces or tabs to use (default = 2 spaces or 1 tab)
-s --silent When on, no output is shown. If enabled, you'll distinguish success from failure by exit code opens in a new tab.
-a --arrays Also sort any arrays if they contain only string elements
-h --help Shows (similar to this) help
-v --version Shows the installed version of your json-sort-cli
-p --pack Skip all package.json files
-d --dry Only output the paths of the files
-c --ci Does nothing, exits with non-zero code if files COULD BE sorted, with zero code if no sort needed.

Put either short or long version of a desired flag, before or after the path or list of paths. For example, all these commands below are the same:

  • jsonsort templates/springsale03 -s
  • jsonsort -s templates/springsale03
  • jsonsort templates/springsale03 --silent
  • jsonsort --silent templates/springsale03

What it does exactly

It sorts JSON files deeply.

That is, it does not matter is it's a plain object within array within array within a plain object - all objects no matter how deep, will be detected and sorted.

If this tool processes any package.json files (put -p to disable this), it will first deep-sort alphabetically, then use format-package (npm opens in a new tab) to arrange keys according to a commonly agreed format — name at the top, depedencies at the bottom etc.

This is a parsing-type application, so written files are also prettified — tabulations and whitespace are fixed to an (arbitrary) order. If you leave the default setting, it will indent using two spaces. If you call it with a flag -t, one tab will be used.

Under the bonnet, this application uses ast-monkey-traverse, sorted-object opens in a new tab, format-package opens in a new tab.

Extra features

  • package.json are first deep-sorted alphabetically, then using format-package (npm opens in a new tab) (on by default, but put -p to disable this)
  • Works on dot files, as long as they are parse-able as JSON
  • Can process a set of files in folder (use wildcards for example, jsonsort "**/packages/*/data/*.json")
  • Broken JSON files don't stop the process, other healthy files from batch are still sorted. Notifies user.
  • System files like .DS_Store are not processed by default, don't worry about excluding them in the input path.

CI mode

When in CI mode, this CLI won't amend the files, only calculate the sorted result, compare the file's contents with it, then exit with a:

  • zero code, if sorting would make no difference to a file
  • non-zero code, if sorting would not make any difference

Basically, your scripts with this CLI would fail on unsorted JSON's. Thanks widerin opens in a new tab for the idea for this feature.

CI mode does not write files, only exits with one code or another.


See it in the monorepo opens in a new tab, on GitHub.


To report bugs or request features or assistance, raise an issue on GitHub opens in a new tab.

Any code contributions welcome! All Pull Requests will be dealt promptly.


MIT opens in a new tab

Copyright © 2010–2021 Roy Revelt and other contributors

Related packages:

📦 json-comb 0.6.1
Command line app to manage sets of JSON files
📦 json-comb-core 7.0.1
The inner core of json-comb
📦 json-variables 11.0.1
Resolves custom-marked, cross-referenced paths in parsed JSON