@ponharu/sort-json


Fast JSON key sorter - Bun-optimized, Node.js compatible.

Features

- Fast: Uses Bun APIs when available (1.5-2x faster JSON parsing)
- Compatible: Falls back to Node.js when Bun is not available
- Zero config: Works out of the box
- CI-friendly: --check mode for validation
- Glob support: Process multiple files with patterns
- Safe JSONC handling: Skips files with comments by default to prevent data loss

Why not...?

| Tool | Issue |
| --------------------------- | --------------------------------- |
| prettier-plugin-sort-json | Requires Prettier (heavy) |
| jq -S | No in-place edit, no glob support |
| json-sort-cli | Node.js only, slower startup |

Installation

``bash


npm

npm install -g @ponharu/sort-json

bun

bun add -g @ponharu/sort-json

pnpm

pnpm add -g @ponharu/sort-json
`

Usage

$3

`bash


Sort a single file

sort-json config.json

Sort multiple files

sort-json "*/.json"

Sort with glob patterns

sort-json "src/*/.json" "config/*.json"
`

$3

`bash


Check if files are sorted (exit 1 if not)


sort-json --check "*/.json"
`

$3

By default, files with comments (JSONC) are skipped to prevent data loss.

`bash


Force processing JSONC (comments will be removed)


sort-json --force tsconfig.json
`

$3

`
Options:
-c, --check Check if files are sorted (exit 1 if not)
-w, --write Write changes to files (default: true)
-f, --force Force processing of JSONC files (comments will be lost)
-i, --indent Indentation width (default: 2)
--tabs Use tabs for indentation
--no-deep Sort top-level keys only
-q, --quiet Suppress output
-h, --help Show help message
-v, --version Show version
`

Integration

$3

`yaml


lefthook.yml


pre-commit:
commands:
sort-json:
glob: "*.json"
exclude: "package-lock.json"
run: sort-json {staged_files}
`

$3

`json
{
"lint-staged": {
"*.json": "sort-json"
}
}
`

$3

`yaml
- name: Check JSON format
run: npx @ponharu/sort-json --check "*/.json"
`

Exit Codes

| Code | Description |
| ---- | -------------------------------- |
| 0 | All files processed successfully |
| 1 | Check failed or error occurred |

Programmatic API

`typescript
import { sortKeys, formatJson } from "@ponharu/sort-json";

const data = { z: 1, a: 2, m: { c: 3, b: 4 } };
const sorted = sortKeys(data);
// { a: 2, m: { b: 4, c: 3 }, z: 1 }

const json = formatJson(sorted, { indent: 2 });
// Formatted JSON string with trailing newline
``

License

MIT