sort-package-json

What is sort-package-json?

The sort-package-json npm package is a utility that automatically sorts the properties in package.json files according to a standard convention. This helps in maintaining consistency and readability in package.json files across different projects.

What are sort-package-json's main functionalities?

Sorting package.json

This feature sorts the keys in a package.json object. It takes an unsorted package.json object as input and returns a string with the keys sorted in a standard order.

const sortPackageJson = require('sort-package-json');
const sortedContent = sortPackageJson(JSON.stringify(packageJsonObject));

CLI Usage

sort-package-json can be used directly from the command line to sort the package.json file in the current directory. This is useful for quick formatting without writing any JavaScript code.

npx sort-package-json

API Usage

The package provides an API that can be used in Node.js scripts. This example reads a package.json file, sorts it, and then writes the sorted JSON back to the file.

const fs = require('fs');
const sortPackageJson = require('sort-package-json');

const packageJson = fs.readFileSync('package.json', 'utf8');
const sortedPackageJson = sortPackageJson(packageJson);

fs.writeFileSync('package.json', sortedPackageJson);

Other packages similar to sort-package-json

prettier-package-json

prettier-package-json is a package that formats package.json files. It sorts the keys and formats the JSON structure. It is similar to sort-package-json but also includes formatting capabilities that adhere to Prettier's styling rules.

fixpack

fixpack is a package that not only sorts the keys in package.json but also validates and fixes missing or incorrect fields. It is more opinionated than sort-package-json and includes additional checks for common issues in package.json files.

README

Sort Package.json

Pass it a JSON string, it'll return a new JSON string, sorted by the keys typically found in a package.json

Pass it an object, it'll return an object sorted by the keys typically found in a package.json

JSON.stringify(sortPackageJson({
  dependencies: {},
  version: '1.0.0',
  keywords: ['thing'],
  name: 'foo',
}), null, 2)
/* string:
{
  "name": "foo",
  "version": "1.0.0",
  "keywords": [
    "thing"
  ],
  "dependencies": {}
}
*/

Install Permanently

API

npm install --save-dev sort-package-json

CLI

npm install --global sort-package-json

CLI Usage:

$ cd my-project
$ cat package.json
{
  "dependencies": {},
  "version": "1.0.0",
  "keywords": [
    "thing"
  ],
  "name": "foo"
}
$ npm i -g sort-package-json
$ sort-package-json
/my-project/package.json is sorted!
$ cat package.json
{
  "name": "foo",
  "version": "1.0.0",
  "keywords": [
    "thing"
  ],
  "dependencies": {}
}

sort-package-json also supports arguments - so you can give it a bunch of package.json file(s) to sort.

$ sort-package-json packages/*/package.json

$ sort-package-json my-package/package.json other-package/package.json

--check flag

When you want to check if your files are sorted, you can run CLI with the --check flag (or -c). This will output a list of not sorted files, if any.

$ sort-package-json **/package.json --check

# 5 matched files are sorted.


$ sort-package-json **/package.json --check
# foo/package.json
# bar/package.json

# 2 of 5 matched files are not sorted.

Run (with npm@5.2+)

npx sort-package-json

Visual Studio Code Extension

https://github.com/unional/vscode-sort-package-json

ESLint Rule with Autofix

https://github.com/kellyselden/eslint-plugin-json-files#supported-rules

Supported Libraries

• AVA
• browserify
• babel
• eslint
• jest
• Istanbul
• Mocha
• node-pre-gyp
• xo
• prettier

Automatically Sort

The package.json file can be sorted automatically before committing, install husky and lint-staged and add the following to the package.json file:

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "package.json": [
      "sort-package-json",
      "git add"
    ]
  }
}

PFAQ: Potential Frequently Asked Questions

How does it sort?

It sorts using sort-object-keys. It sorts using the well-known keys of a package.json. For the full list it's just easier to read the code. It sorts sub-keys too - sometimes by a well-known order, other times alphabetically. The initial order was derived from the package.json docs with a few extras added for good measure.

It doesn't sort X?

Cool. Send a PR! It might get denied if it is a specific vendor key of an unpopular project (e.g. "my-super-unknown-project"). We sort keys like "browserify" because it is a project with millions of users. If your project has, say, over 100 users, then we'll add it. Sound fair?

Isn't this just like Project X?

Could be. I wanted this one because at the time of writing, nothing is:

• Zero config
• Able to be used in a library
• Quiet (i.e. not spitting out annoying log messages, when used in a library mode)

What?! Why would you want to do this?!

Well, it's nice to have the keys of a package.json in a well sorted order. Almost everyone would agree having "name" at the top of a package.json is sensible (rather than sorted alphabetically or somewhere silly like the bottom), so why not the rest of the package.json?