prettier-plugin-pkg

An opinionated package.json formatter plugin for Prettier, based on prettier-plugin-package.

Prettier is an opinionated code formatter. It enforces a consistent style by parsing your code and re-printing, taking various rules into account.

This plugin adds support for package.json files used within NPM modules, npm, yarn and VSCode is supported out of box.

Requirements

prettier-plugin-pkg is an evergreen module. 🌲 This module requires an LTS Node version (v12.0.0+).

Install

# npm
npm i -D prettier prettier-plugin-pkg

# yarn
yarn add -D prettier prettier-plugin-pkg

Usage

Once installed, Prettier plugins must be added to .prettierrc:

{
  "plugins": ["prettier-plugin-pkg"]
}

Then:

# npx
npx prettier --write package.json

# yarn
yarn prettier --write package.json

Rules

This plugin enforces its own set of opinionated rules:

Engines

Keys in engines are ordered alphabetically.

Files

Keys in files are ordered alphabetically (keeping the negations below), followed by README.md and LICENSE if they exist in the array.

Scripts

Keys in scripts are ordered alphabetically. Use prefixes wisely to properly order child scripts. e.g. lint, lint:ts.

Sorting

Top-level keys are sorted according to a style commonly seen in the packages of @JounQin, @1stG and @unts. Known keys, and their order are

[
  // schema definition
  "$schema",

  // meta
  "name",
  "version",
  "type",
  "flat",
  "displayName",
  "description",
  "categories",
  "repository",
  "homepage",
  "bugs",
  "donate",
  "funding",
  "sponsor",
  "author",
  "publisher",
  "maintainers",
  "contributors",
  "license",
  "preview",
  "private",
  "workspaces",

  // constraints
  "languageName",
  "packageManager",
  "engines",
  "cpu",
  "os",
  "libc",
  "devEngines",

  // entries
  "man",
  "bin",
  "main",
  "types",
  "typings",
  "typesVersions",
  "module",
  "imports",
  "exports",
  "esnext",
  "es2020",
  "esm2020",
  "fesm2020",
  "es2015",
  "esm2015",
  "fesm2015",
  "es5",
  "esm5",
  "fesm5",
  "browser",
  "umd",
  "jsdelivr",
  "unpkg",

  // contents and utils
  "directories",
  "files",
  "keywords",
  "scripts",
  "config",

  // dependencies
  "bundledDependencies",
  "peerDependencies",
  "peerDependenciesMeta",
  "dependencies",
  "dependenciesMeta",
  "optionalDependencies",
  "devDependencies",
  "overrides",
  "resolutions",
  "publishConfig",
  "sideEffects",

  // vscode spec
  "icon",
  "badges",
  "galleryBanner",
  "activationEvents",
  "contributes",
  "markdown",
  "qna",
  "extensionPack",
  "extensionDependencies",
  "extensionKind"
]

Unknown keys, or keys not part of the list above, will be alphabetically sorted and added to the end of the file. Note that this list takes into account both npm and yarn keys.

You can also use the packageSortOrder option to specify a custom sort order, or use the packageSortOrderPreset option to use a preset sort order:

npm: sorts by npm's document
npm-plus: sorts by sort-package-json and therefore is compatible to prettier-plugin-packagejson

Forthcoming

Forthcoming rules include:

[ ] Author format
[ ] Repository format

Format Options

interface FormatOptions {
  // An array of property names to sort the package.json properties by.
  packageSortOrder?: string[]
  // An array of property names to ignore when sorting the package.json properties.
  packageIgnoreSort?: string[]
  // A preset for the package.json sort order.
  packageSortOrderPreset?: 'npm' | 'npm-plus'
}

Acknowledgements

Thanks for @shellscape's original great work of prettier-plugin-package again.

Sponsors and Backers

Backers

1stG	RxTS	UnTS