Prettier Package JSON

2.8.0 verified Sat Apr 25 auth: no javascript

Prettier-package-json is a focused tool for formatting package.json files with consistent key ordering, script sorting, and author/contributor normalization. Version 2.8.0 is the current stable release, with active maintenance and monthly releases. It differs from generic JSON formatters by applying npm-specific rules: opinionated key order, smart script sorting (keeping pre/post scripts adjacent), filtering automatically included files from the `files` array, and expanding/contracting user objects. It provides both a CLI and programmatic API, supports pre-commit hooks via lint-staged, and is configurable via options like --expand-users. Designed for Node.js environments, it outputs valid JSON with deterministic formatting.

Common errors

error Error: Cannot find module 'prettier-package-json' ↓

cause Package not installed or misspelled in require/import.

fix

Run npm install prettier-package-json --save-dev or yarn add prettier-package-json --dev.

error TypeError: format is not a function ↓

cause Incorrect import: using default import instead of named export.

fix

Use import { format } from 'prettier-package-json' or const { format } = require('prettier-package-json').

error Error: Expected a valid JSON object, got string ↓

cause Passed raw JSON string instead of parsed object to format().

fix

Parse the JSON string first: const pkg = JSON.parse(rawString); then call format(pkg).

error Error: Options object should not contain property 'sortScripts' ↓

cause Using deprecated options in v2.5+.

fix

Remove sortScripts and sortFiles from options. Sorting is always applied; use noSort: true to disable.

error TypeError: Cannot read property 'sort' of undefined ↓

cause Passed null or undefined as the package object.

fix

Ensure the argument to format() is a valid parsed JSON object, not null or undefined.

Warnings

breaking In v1.x, format() mutated the input object. In v2+, it returns a new object and the input is not modified. ↓

fix Treat the returned value as the formatted output; do not rely on the original object being changed.

deprecated The options `sortScripts` and `sortFiles` have been deprecated in favor of unified sorting behavior. ↓

fix Remove those options; sorting is always applied. Use noSort option to disable sorting entirely.

gotcha The CLI uses `--write` to overwrite the file, but it does not create backups. Always commit before running. ↓

fix Use version control or manually back up package.json before running with --write.

gotcha The `files` field is automatically filtered: it excludes files that npm always includes (e.g., package.json, README, CHANGELOG). ↓

fix Do not include npm-implied files explicitly; they will be removed on format.

gotcha When using `expandUsers: false` (default), author, contributors, and maintainers are converted to string format. This may lose information if objects contain extra keys beyond name/email/url. ↓

fix Set `expandUsers: true` to keep object format, or ensure objects only have name/email/url.

Install

npm install prettier-package-json

yarn add prettier-package-json

pnpm add prettier-package-json

Imports

format
wrong
```
const format = require('prettier-package-json')
```
correct
```
import { format } from 'prettier-package-json'
```
ESM import for the primary formatting function. CJS require is also supported but named export must be destructured.
check
wrong
```
import check from 'prettier-package-json'
```
correct
```
import { check } from 'prettier-package-json'
```
check is a named export, not default. Use check() to verify formatting without writing.
defaultOptions
```
import { defaultOptions } from 'prettier-package-json'
```
Predefined options object for customization. Available since v2.0.

Quickstart

Reads package.json, formats with indent and expandUsers options, writes back, and demonstrates the check function.

const { format, check } = require('prettier-package-json');
const fs = require('fs');

const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
const formatted = format(pkg, {
  indent: '  ',
  expandUsers: false,
  useTabs: false
});
fs.writeFileSync('./package.json', JSON.stringify(formatted, null, 2) + '\n');
console.log('Formatted package.json');

// Check if already formatted
const isFormatted = check(pkg, { expandUsers: true });
console.log('Is formatted:', isFormatted);