format

Format package.json files in your monorepo. Sorts fields into consistent order and alphabetises nested fields. Use this to maintain readable, diff-friendly package.json files. Does not change version numbers—use fix for that.

Examples

# Fix every formatting issue in the monorepo
syncpack format
# List all formatting issues in the monorepo
syncpack format --check
# Check the formatting of one package
syncpack format --check --source 'packages/pingu/package.json'
# See more examples
syncpack format --help
# See a short summary of options
syncpack format -h

Options

--check

Lint formatting instead of fixing it and exit with a status code of 1 if issues are found.

syncpack format --check

--config <file-path>

syncpack searches the monorepo root directory for a config file which follows its naming convention, but this can be overridden by providing a path to a specific configuration file instead.

The only requirement is that the file must have a file extension and that it is one of .cjs, .cts, .js, .json, .mjs, .mts, .ts, .yaml, or .yml.

syncpack format --config ./config/syncpack.json

--dry-run

Cause syncpack to behave identically as when applying fixes, but never writing to disk.

syncpack format --dry-run

--log-levels <comma-separated-log-level-names>

Control how detailed the log output should be

Level	What is written to this channel
info	The standard output which forms syncpack's UI, including lint issues
warn	Possible mistakes in your setup, or highlights of known gaps in syncpack
error	Fatal exceptions or errors outside the normal running of syncpack
debug	Extremely verbose detail on why syncpack assigns each status code

# Turn off logging completely
syncpack format --log-levels off
# Only show verbose debugging logs
syncpack format --log-levels debug
# Show everything
syncpack format --log-levels error,warn,info,debug

--no-ansi

Syncpack will print colours and clickable hyperlinks to the terminal using ANSI escape code unless this option is set.

syncpack format --no-ansi

--reporter <reporter-name>

Set the output format. Defaults to pretty which prints human-readable output with colours and formatting. Use json to output one line of newline-delimited JSON (NDJSON) per formatting mismatch. See also the json command which outputs the state of every instance in your repo.

Each line has the type FormatJsonOutput:

// This JSON has been formatted but appears on a single line in syncpack
{
  "package": "my-app",
  "filePath": "packages/my-app/package.json",
  "property": [
    "scripts"
  ],
  "statusCode": "PropertyIsNotSortedAz"
}

# Default human-readable output
syncpack format --reporter pretty
# Machine-readable NDJSON output
syncpack format --reporter json
# Pipe to jq to filter by status code
syncpack format --reporter json | jq 'select(.statusCode == "PackagePropertiesAreNotSorted")'

--source <file-pattern>

Only run syncpack format on package.json files matching the provided pattern(s).

Syncpack will look in the following places for glob patterns matching package.json files, in this order of precedence, and stop looking when a match is found:

If --source CLI options are provided, use those.
If source is defined in configuration, use that.
If using npm workspaces or Yarn workspaces, read workspaces from ./package.json.
If using pnpm, read packages from ./pnpm-workspace.yaml.
If using Lerna, read packages from ./lerna.json.
Default to 'package.json' and 'packages/*/package.json'.

# only the root package
syncpack format --source 'package.json'
# only packages matching a glob
syncpack format --source 'packages/beta-*'
# multiple values can be provided
syncpack format --source 'package.json' --source 'packages/beta-*'

--help

Display a list of CLI options and other help information.

# Display a short summary of commands and options
syncpack format -h
# Display full help with examples
syncpack format --help