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

CLI

Run via npx (npm@5.2+ required)

npx sort-package-json

Install

npm install --global sort-package-json

Usage

$ cd my-project
$ cat package.json
{
  "dependencies": {
    "sort-package-json": "1.0.0",
    "sort-object-keys": "1.0.0"
  },
  "version": "1.0.0",
  "name": "my-awesome-project"
}

$ npx sort-package-json
package.json is sorted!

Found 1 file.
1 file successfully sorted.

$ cat package.json
{
  "name": "my-awesome-project",
  "version": "1.0.0",
  "dependencies": {
    "sort-object-keys": "1.0.0",
    "sort-package-json": "1.0.0"
  }
}

CLI also supports multi file paths or glob - so you can give it a bunch of package.json file(s) to sort.

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

$ sort-package-json "package.json" "packages/*/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

Found 5 files.
5 files were already sorted.

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

Found 5 files.
3 files were not sorted.
2 files were already sorted.

--quiet flag

In order to silence any successful output, you can run CLI with the --quiet flag (or -q). This will stop the CLI from outputting if it runs successfully, but won't effect error messages and the exit code.

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

--stdin flag

To read from stdin and output the result to stdout use the --stdin flag.

$ cat package.json | sort-package-json --stdin

This can, for instance, be used to generate a diff before changing package.json.

$ ( PKG="./package.json" ; cat "${PKG?}" | sort-package-json --stdin | diff "${PKG?}" - ; )

API

Install

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

Usage

sortPackageJson(packageJson, options?)

Pass a JSON string, return a new sorted JSON string.
Pass a JSON object, return a new sorted JSON object.

import sortPackageJson from 'sort-package-json'

const packageJsonString = `{
  "dependencies": {
    "sort-package-json": "1.0.0",
    "sort-object-keys": "1.0.0"
  },
  "version": "1.0.0",
  "name": "my-awesome-project"
}`

console.log(sortPackageJson(packageJsonString))
/* => string:
{
  "name": "my-awesome-project",
  "version": "1.0.0",
  "dependencies": {
    "sort-object-keys": "1.0.0",
    "sort-package-json": "1.0.0"
  }
}
*/

const packageJsonObject = JSON.parse(packageJsonString)
console.log(sortPackageJson(packageJsonObject))
/* => object:
{
  name: 'my-awesome-project',
  version: '1.0.0',
  dependencies: {
    'sort-object-keys': '1.0.0',
    'sort-package-json': '1.0.0'
  }
}
*/

options.sortOrder

Type: string[] | Function
Default: sortPackageJson.sortOrder

Custom ordering array or comparator function.

If an array, sort keys in ordering of options.sortOrder.

Notice: fields not in this array, will still sort by defaultSortOrder

const sorted = sortPackageJson(packageJsonObject, {
  sortOrder: ['version'],
})

console.log(Object.keys(sorted))

// -> [ 'version', 'name', 'dependencies' ]
//                 ^^^^^^^^^^^^^^^^^^^^^^
//                 `name` and `dependencies` are sorted by defaultSortOrder

If a function, sort fields by Array#sort(options.sortOrder)

const sorted = sortPackageJson(packageJsonObject, {
  sortOrder(left, right) {
    return left.localeCompare(right)
  },
})

console.log(Object.keys(sorted))

// -> [ 'dependencies', 'name', 'version' ]

Related tools

• ESLint Rule with Autofix
• Prettier Plugin
• Visual Studio Code Extension

Supported Libraries

• AVA
• Babel
• Browserify
• c8
• commitlint
• ESLint
• Husky
• Istanbul
• Jest
• lint-staged
• Mocha
• node-pre-gyp
• npm-package-json-lint
• oclif
• pnpm
• Prettier
• remark
• semantic-release
• stylelint
• Tap
• xojs

Alphabetically ordered.

Automatically Sort

The package.json file can be sorted automatically before committing.

npm install husky lint-staged --save-dev
npm pkg set scripts.prepare="husky install"
npm run prepare
npx husky add .husky/pre-commit "npx lint-staged"

Add the following to your package.json file

{
  "lint-staged": {
    "package.json": "sort-package-json"
  }
}

See Husky and lint-staged for more information.

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 check the default rules. 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)

I would like this tool to be configurable with a config file or command line arguments.

The lack of configuration here is a feature, not a bug. The intent of this tool is that a user can open a package json and always expect to see keys in a particular order. If we add a configuration for this tool, then that promise is broken, as users will first need to look at the configuration for each project to learn the ways in which this tool will change the package.json. The structure of the package.json should always be predictable & deterministic from project to project. I think the reason why this project is well used is because it is not another "tool" you have to set up with yet another JSON file and more cruft in your project to support it. You run a command and it does what it says on the tin.

A lot of people who ask for configuration cite the use case that they simply don't like the given order that exists and want to make sweeping changes. To me this seems far better suited to simply making a fork of this project as then you can go far further than specifying configuration.

What is the order this package defaults to?

The default order is exported as a sortOrder object.

Properties mentioned in the npm docs

1. name
2. version
3. private
4. description
5. keywords
6. homepage
7. bugs
8. repository
9. funding
10. license
11. author
12. contributors
13. main
14. browser
15. bin
16. man
17. directories
18. files
19. workspaces
20. scripts
21. config
22. dependencies
23. engines
24. os
25. cpu

Full list of recognized properties

1. $schema
2. name
3. displayName
4. version
5. private
6. description
7. categories
8. keywords
9. homepage
10. bugs
11. repository
12. funding
13. license
14. qna
15. author
16. maintainers
17. contributors
18. publisher
19. sideEffects
20. type
21. imports
22. exports
23. main
24. svelte
25. umd:main
26. jsdelivr
27. unpkg
28. module
29. source
30. jsnext:main
31. browser
32. react-native
33. types
34. typesVersions
35. typings
36. style
37. example
38. examplestyle
39. assets
40. bin
41. man
42. directories
43. files
44. workspaces
45. binary
46. scripts
47. betterScripts
48. contributes
49. activationEvents
50. husky
51. simple-git-hooks
52. pre-commit
53. commitlint
54. lint-staged
55. nano-staged
56. config
57. nodemonConfig
58. browserify
59. babel
60. browserslist
61. xo
62. prettier
63. eslintConfig
64. eslintIgnore
65. npmpkgjsonlint
66. npmPackageJsonLintConfig
67. npmpackagejsonlint
68. release
69. remarkConfig
70. stylelint
71. ava
72. jest
73. jest-junit
74. jest-stare
75. mocha
76. nyc
77. c8
78. tap
79. resolutions
80. dependencies
81. devDependencies
82. dependenciesMeta
83. peerDependencies
84. peerDependenciesMeta
85. optionalDependencies
86. bundledDependencies
87. bundleDependencies
88. extensionPack
89. extensionDependencies
90. flat
91. packageManager
92. engines
93. engineStrict
94. volta
95. languageName
96. os
97. cpu
98. preferGlobal
99. publishConfig
100. icon
101. badges
102. galleryBanner
103. preview
104. markdown
105. pnpm

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?