sort-package-json

Sort an Object or package.json based on the well-known package.json keys


Keywords
keys, object, sort
License
MIT
Install
npm install sort-package-json@1.23.0

Documentation

Sort Package.json

Build Status NPM Version

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

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

Supported Libraries

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?