prettier-plugin-packagejson

prettier-plugin-packagejson is a lightweight Prettier plugin that keeps package.json files consistently ordered by delegating to sort-package-json whenever Prettier formats a file named package.json. It hooks into Prettier’s built-in json-stringify parser rather than shipping a parser of its own, so every other formatting behavior — indentation, trailing commas, line width — stays exactly as Prettier already handles it.

The plugin exposes a single packageSortOrder option for teams that want a custom key ordering instead of the sort-package-json default, and it explicitly no-ops on any JSON file that isn’t literally named package.json (composer.json, package-lock.json, and case-variant paths are all excluded), so it can be dropped into an existing Prettier config without touching unrelated files.

What You Get

• Automatic package.json key sorting on every Prettier format/write pass
• Zero-config integration — just add it to Prettier’s plugins array
• Optional custom sort order via the packageSortOrder option
• Path-based detection that only touches files literally named package.json

Common Use Cases

• Enforcing consistent package.json formatting across a monorepo in CI
• Auto-fixing key order as part of a pre-commit hook or lint-staged step
• Standardizing package.json output from codegen or scaffolding tools that write package.json files

Under The Hood

Architecture prettier-plugin-packagejson is a single-file plugin (lib/index.cjs) that wraps Prettier’s built-in json-stringify parser rather than defining its own: it spreads the existing parser object and overrides only its preprocess hook, first delegating to any preprocess Prettier or another plugin already registered before conditionally running sort-package-json against files whose path matches a package.json-only regex. There is no internal module structure or state to reason about — the plugin’s entire contract is testPath, parsers, and options — which keeps the design easy to follow but also means any change to Prettier’s internal parser shape would break it with no fallback path.

Tech Stack The plugin has exactly one runtime dependency, sort-package-json, and treats prettier itself as an optional peer dependency so it doesn’t force a version on consuming projects. It ships hand-written CommonJS (lib/index.cjs) and a hand-written .d.cts declaration file with no build/bundle step. Testing relies on Node’s native node:test runner with built-in snapshot assertions and coverage reporting rather than a heavier framework like Jest, and the repository wires up GitHub Actions for CI/release, Renovate for automated dependency bumps, and Codecov for coverage tracking.

Code Quality Unit tests cover both the path-matching logic and end-to-end formatting behavior, including a dedicated test asserting that an existing preprocess hook still runs when the plugin chains onto it — a detail that’s easy to regress silently. There’s no separate ESLint configuration; the only enforced lint step is Prettier’s own formatting check. Error handling is minimal: resolving prettier/parser-babel is wrapped in a try/catch to tolerate the optional peer dependency, but there’s limited handling beyond that single guard.

API Design Adopting the plugin requires a single line in a Prettier config’s plugins array and, optionally, one packageSortOrder option — there is no additional API surface to learn. TypeScript consumers get real editor support because the package augments Prettier’s own Options interface via declaration merging, so packageSortOrder autocompletes and type-checks like any built-in Prettier option. The README documents installation and the one option concisely, though it offers little beyond that for edge cases like how the plugin interacts with other json-stringify-consuming plugins.