Gudahtt
prettier-plugin-sort-json
A plugin for Prettier that sorts JSON files by property name.
Description
This plugin adds a JSON preprocessor that will sort JSON files alphanumerically by key.
By default, top-level object entries are sorted by key lexically using Array.sort, according to each character's Unicode code point value. It can be configured to sort recursively, and with a custom sort order.
Example
Before:
{
"z": null,
"a": null,
"0": null,
"exampleNestedObject": {
"z": null,
"a": null
}
}After:
{
"0": null,
"a": null,
"exampleNestedObject": {
"z": null,
"a": null
},
"z": null
}Exceptions
Non-objects
This is meant to sort objects. JSON files with a top-level value that is not an object are skipped.
JSON files with dedicated Prettier parsers
This will not sort
package.json,package-lock.json, orcomposer.json. This plugin only affects thejsonparser used by Prettier. Prettier uses an alternate parser (json-stringify) for those three specific files (See here for details).JSON embedded in other files
This will not sort JSON objects within other types of files, such as JavaScript or TypeScript files. This is just for sorting JSON files.
Requirements
This module requires an LTS Node version (v16.0.0+), and prettier v3+.
We are maintaining support for Prettier v2 on version 2 of this plugin. See the main-v2 branch for instructions on using v2 of this plugin.
Install
Using npm:
npm install --save-dev prettier-plugin-sort-jsonUsing yarn:
yarn add --dev prettier-plugin-sort-jsonThen follow these instructions to load the plugin.
There are some additional configuration options available (described below), but they are all optional.
Example Prettier configuration
{
"plugins": ["prettier-plugin-sort-json"]
}Configuration
These configuration options are all optional. Each option can be set as a CLI flag, or as an entry in your Prettier configuraton (e.g. in your .prettierrc file).
Here is an example .prettierrc file with all default options set:
{
"plugins": ["prettier-plugin-sort-json"],
"jsonRecursiveSort": false,
"jsonSortOrder": "{\"*\": \"lexical\"}"
}JSON Recursive Sort
Sort JSON objects recursively, including all nested objects. This also sorts objects within JSON arrays.
| Default | CLI | Configuration |
|---|---|---|
false |
--json-recursive-sort |
jsonRecursiveSort: <bool> |
JSON Sort Order
Use a custom sort order. This is specified as a JSON string that maps exact strings or regular expressions to sorting algorithms.
| Default | CLI | Configuration |
|---|---|---|
"" |
--json-sort-order '<string>' |
jsonSortOrder: <string> |
Here is an example JSON sort order string:
'{ "placeThisFirst": null, "/^[^\\d+]/": "lexical", "/^\\d+/": "numeric" }'This sorts the key "placeThisFirst" ahead of all others. After that, the set of all keys that don't start with a number are sorted lexically. Lastly, the set of keys that start with a number are sorted numerically.
Each jsonSortOrder key represents a literal key value or a category of keys, represented by a regular expression. Regular expressions are identified by leading and trailing forward slashes, along with some number of paths optionally following the trailing slash (supported flags are i, m, s, and u).
Each jsonSortOrder value represents the sorting algorithm to use within that category. If the value is null, the default sorting algorithm lexical is used. Here are the supported sorting algorithms:
| Sorting Algorithm | Description |
|---|---|
lexical |
Sort lexically (i.e. lexicographically). This is the default. |
numeric |
For keys that are prefixed with a number, sort by that number in ascending order. Otherwise sort lexically. |
reverseLexical |
Reverse-order lexical sort. |
reverseNumeric |
Reverse-order numeric sort. |
caseInsensitiveLexical |
Case-insensitive lexical sort. |
caseInsensitiveNumeric |
Case-insensitive numeric sort. |
caseInsensitiveReverseLexical |
Case-insensitive reverse-order lexical sort. |
caseInsensitiveReverseNumeric |
Case-insensitive reverse-order numeric sort. |
none |
Do not sort. |
The order of the jsonSortOrder configuration determines how the keys in each category are sorted in relation to each other. Keys that do not match any defined category are treated as being in an implied last category, with lexical sorting.
Note: Escaping can be tricky, especially if you are using regular expression sort keys. These regular expressions are configured as strings, so any backslashes require an additional escape (e.g. notice the double-backslash here:
"/^\\d+/").If this key is configured as part of a JSON Prettier configuration file (
prettierrc.json), all double-quotes and backslashes need to be escaped again. For example, the example JSON sort order string would would be"{ \"placeThisFirst\": null, \"/^[^\\\\d+]/\": \"lexical\", \"/^\\\\d+/\": \"numeric\" }.
Ignoring files
This plugin can be used on specific files using Prettier configuration overrides. By configuring this plugin in an override, you can control which files it is applied to. Overrides can also allow using different configuration for different files (e.g. different sort order)
For example, lets say you had the following requirements:
- No sorting of JSON by default
- Shallow (non-recursive) sort JSON in the
json/directory - Do not sort the file
json/unsorted.json - Recursively sort
recursively-sorted.json
You could do that with this .prettierrc.json file:
{
"overrides": [
{
"excludedFiles": ["./json/unsorted.json"],
"files": ["./json/**"],
"options": {
"plugins": ["prettier-plugin-sort-json"]
}
},
{
"files": ["./json/recursive-sorted.json"],
"options": {
"jsonRecursiveSort": true
}
}
]
}Contributing
See CONTRIBUTING.md