prettier-package-json

Prettier package.json

prettier-package-json is a JSON formatter inspired by prettier. It removes all original styling and ensures that the outputted package.json conforms to a consistent style. By default it uses opinionated defaults but can be configured to your individual needs.

Features

Consistent key order

Keys in package.json will be sorted in an opinionated order but may be configured to your own preferences.

Input:

{
  "description": "Prettier formatter for package.json files",
  "name": "prettier-package-json",
  "license": "MIT",
  "version": "1.0.1",
  "author": "Cameron Hunter <hello@cameronhunter.co.uk>"
}

Output:

{
  "name": "prettier-package-json",
  "description": "Prettier formatter for package.json files",
  "author": "Cameron Hunter <hello@cameronhunter.co.uk>",
  "license": "MIT",
  "version": "1.0.1"
}

Sensibly sorted scripts

The scripts field is sorted alphabetically but keeps pre and post scripts surrounding their named script.

Input:

{
  "name": "prettier-package-json",
  "version": "1.0.1",
  "scripts": {
    "test": "test",
    "pretest": "pretest",
    "version": "version",
    "postversion": "postversion",
    "build": "build"
  }
}

Output:

{
  "name": "prettier-package-json",
  "version": "1.0.1",
  "scripts": {
    "build": "build",
    "pretest": "pretest",
    "test": "test",
    "version": "version",
    "postversion": "postversion"
  }
}

Expand/contract author, contributors, and maintainers

The author, contributors and maintainers fields will be shortened to their string versions and sorted by name. Use the --expand-users option if you prefer user objects.

Input:

{
  "name": "prettier-package-json",
  "version": "1.0.1",
  "author": {
    "name": "Cameron Hunter",
    "email": "hello@cameronhunter.co.uk",
    "url": "https://cameronhunter.co.uk"
  },
  "contributors": ["Barry", "Adam <adam@email.com>"]
}

Output:

{
  "name": "prettier-package-json",
  "version": "1.0.1",
  "author": "Cameron Hunter <hello@cameronhunter.co.uk> (https://cameronhunter.co.uk)",
  "contributors": ["Adam <adam@email.com>", "Barry"]
}

Filter and sort files field

Some files are included or excluded automatically by npm, these are removed from the files field before sorting alphabetically.

Input:

{
  "name": "prettier-package-json",
  "version": "1.0.1",
  "main": "src/index.js",
  "files": ["src/index.js", "src", "CHANGELOG.md", "readme.md", "package-lock.json"]
}

Output:

{
  "name": "prettier-package-json",
  "version": "1.0.1",
  "main": "src/index.js",
  "files": ["src"]
}

Usage

Install:

yarn add prettier-package-json --dev

You can install it globally if you like:

yarn global add prettier-package-json

We're defaulting to yarn but you can use npm if you like:

npm install [-g] prettier-package-json

CLI

Run prettier-package-json through the CLI with this script. Run it without any arguments to see the options.

To format a file in-place, use --write. You may want to consider committing your file before doing that, just in case.

prettier-package-json [opts] [filename]

In practice, this may look something like:

prettier-package-json --write ./package.json

Pre-commit hook for changed files

You can use this with a pre-commit tool. This can re-format your files that are marked as "staged" via git add before you commit.

1. lint-staged

Install it along with husky:

yarn add lint-staged husky --dev

and add this config to your package.json:

{
  "scripts": {
    "precommit": "lint-staged"
  },
  "lint-staged": {
    "package.json": ["prettier-package-json --write", "git add"]
  }
}

See https://github.com/okonet/lint-staged#configuration for more details about how you can configure lint-staged.

2. bash script

Alternately you can just save this script as .git/hooks/pre-commit and give it execute permission:

#!/bin/sh
packagejsonfiles=$(git diff --cached --name-only --diff-filter=ACM | grep 'package\.json
API
The API has two functions, exported as format and check. Usage is as follows:
import { format, check } from 'prettier-package-json';

const options = {}; // optional

format(json, options);
check(json, options);
check checks to see if the file has been formatted with prettier-package-json given those options and returns a Boolean.
This is similar to the --list-different parameter in the CLI and is useful for running in CI scenarios.
CI
For usage in CI scenarios, you can use the --list-different CLI flag. The command will list all invalid files and return
with a proper default error code, so that in case of an error or invalid file the build pipeline automatically fails.
These are the status codes:

0: all files valid, no error occured.
1: an error ocurred, for example a JSON parse error. See message on stderr for details.
2: not all files are valid.

These exit codes are only set when in --list-different mode.
Options
prettier-package-json ships with a handful of customizable format options, usable in both the CLI, API, and configuration file.



Option
Default
CLI override
API override



Tab Width - Specify the number of spaces per indentation-level.
2
--tab-width <int>
tabWidth: <int>


Tabs - Indent lines with tabs instead of spaces.
false
--use-tabs
useTabs: <bool>


Expand Users - Expand author and contributors into objects.
false
--expand-users
expandUsers: <bool>


Key Order - Specify the order of keys.
See default options
--key-order <comma,separated,list...>
keyOrder: <array|function>


A configuration file will be searched for using cosmiconfig rules:

prettier-package-json field in package.json.
prettier-package-json file (JSON or YAML), extentionless "rc" file.
prettier-package-json file with the extensions .json, .yaml, .yml, .js, or .cjs.
prettier-package-json.config.js or prettier-package-json.config.cjs CommonJS module.

Configuration file may also be passed using the --config CLI parameter.
Contributing
See CONTRIBUTING.md.
 | tr '\n' ' ')
[ -z "$packagejsonfiles" ] && exit 0

diffs=$(node_modules/.bin/prettier-package-json -l $packagejsonfiles)
[ -z "$diffs" ] && exit 0

echo "here"
echo >&2 "package.json files must be formatted with prettier-package-json. Please run:"
echo >&2 "node_modules/.bin/prettier-package-json --write "$diffs""

exit 1

API

The API has two functions, exported as __INLINE_CODE_18__ and __INLINE_CODE_19__. Usage is as follows:

__CODE_BLOCK_16__

__INLINE_CODE_20__ checks to see if the file has been formatted with __INLINE_CODE_21__ given those options and returns a Boolean. This is similar to the __INLINE_CODE_22__ parameter in the CLI and is useful for running in CI scenarios.

CI

For usage in CI scenarios, you can use the __INLINE_CODE_23__ CLI flag. The command will list all invalid files and return with a proper default error code, so that in case of an error or invalid file the build pipeline automatically fails.

These are the status codes:

• __INLINE_CODE_24__: all files valid, no error occured.
• __INLINE_CODE_25__: an error ocurred, for example a JSON parse error. See message on __INLINE_CODE_26__ for details.
• __INLINE_CODE_27__: not all files are valid.

These exit codes are only set when in __INLINE_CODE_28__ mode.

Options

__INLINE_CODE_29__ ships with a handful of customizable format options, usable in both the CLI, API, and configuration file.

Option	Default	CLI override	API override
Tab Width - Specify the number of spaces per indentation-level.	__INLINE_CODE_30__	__INLINE_CODE_31__	__INLINE_CODE_32__
Tabs - Indent lines with tabs instead of spaces.	__INLINE_CODE_33__	__INLINE_CODE_34__	__INLINE_CODE_35__
Expand Users - Expand author and contributors into objects.	__INLINE_CODE_36__	__INLINE_CODE_37__	__INLINE_CODE_38__
Key Order - Specify the order of keys.	See default options	__INLINE_CODE_39__	__INLINE_CODE_40__

A configuration file will be searched for using __INLINE_CODE_41__ rules:

• __INLINE_CODE_42__ field in __INLINE_CODE_43__.
• __INLINE_CODE_44__ file (JSON or YAML), extentionless "rc" file.
• __INLINE_CODE_45__ file with the extensions __INLINE_CODE_46__, __INLINE_CODE_47__, __INLINE_CODE_48__, __INLINE_CODE_49__, or __INLINE_CODE_50__.
• __INLINE_CODE_51__ or __INLINE_CODE_52__ CommonJS module.

Configuration file may also be passed using the __INLINE_CODE_53__ CLI parameter.

Contributing

See CONTRIBUTING.md.