docs: update README.md (#107)

* docs: update README.md * docs: add `options.sortOrder` * fix: move npx command to top * docs: fix libraries orders
keithamus · Dec 30, 2019 · df1c4e2 · df1c4e2
1 parent 71b28d3
commit df1c4e2
Showing 1 changed file with 117 additions and 72 deletions.
diff --git a/README.md b/README.md
@@ -1,126 +1,172 @@
-## Sort Package.json
+# Sort Package.json
 
 [![Build Status](https://travis-ci.org/keithamus/sort-package-json.svg)](https://travis-ci.org/keithamus/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
+## CLI
 
-Pass it an object, it'll return an object sorted by the keys typically found in a package.json
+### Run via npx (npm@5.2+ required)
 
-```js
-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
 ```bash
-npm install --save-dev sort-package-json
+npx sort-package-json
 ```
 
-#### CLI
+### Install
+
 ```bash
 npm install --global sort-package-json
 ```
 
-### CLI Usage:
+### Usage
 
 ```bash
 $ cd my-project
 $ cat package.json
 {
-  "dependencies": {},
+  "dependencies": {
+    "sort-package-json": "1.0.0",
+    "sort-object-keys": "1.0.0"
+  },
   "version": "1.0.0",
-  "keywords": [
-    "thing"
-  ],
-  "name": "foo"
+  "name": "my-awesome-project"
 }
-$ npm i -g sort-package-json
-$ sort-package-json
-/my-project/package.json is sorted!
-$ cat package.json
+
+$ npx sort-package-json
+package.json is sorted!
+
+cat package.json
 {
-  "name": "foo",
+  "name": "my-awesome-project",
   "version": "1.0.0",
-  "keywords": [
-    "thing"
-  ],
-  "dependencies": {}
+  "dependencies": {
+    "sort-object-keys": "1.0.0",
+    "sort-package-json": "1.0.0"
+  }
 }
 ```
 
-`sort-package-json` also supports arguments - so you can give it a bunch of package.json file(s) to sort.
+CLI also supports multi file paths or [`glob`](https://github.com/sindresorhus/globby) - so you can give it a bunch of `package.json` file(s) to sort.
 
 ```bash
-$ sort-package-json packages/*/package.json
+$ sort-package-json "my-package/package.json" "other-package/package.json"
 
-$ 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.
 
 ```bash
-$ sort-package-json **/package.json --check
+$ sort-package-json "**/package.json" --check
 
 # 5 matched files are sorted.
 
 
-$ sort-package-json **/package.json --check
+$ sort-package-json "**/package.json" --check
 # foo/package.json
 # bar/package.json
 
 # 2 of 5 matched files are not sorted.
 ```
 
+## API
 
-### Run (with npm@5.2+)
+### Install
 
 ```bash
-npx sort-package-json
+npm install --save-dev sort-package-json
 ```
 
-### Visual Studio Code Extension
+### Usage
 
-<https://github.com/unional/vscode-sort-package-json>
+```js
+sortPackageJson(jsonIsh, options?)
+```
 
-### ESLint Rule with Autofix
+Pass a JSON string, return a new sorted JSON string.
+Pass a JSON object, return a new sorted JSON object.
 
-<https://github.com/kellyselden/eslint-plugin-json-files#supported-rules>
+```js
+const sortPackageJson = require('sort-package-json')
 
-### Supported Libraries
+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
+
+custom sortOrder
+
+```js
+console.log(sortPackageJson(packageJsonObject, {
+  sortOrder: ['version', 'name', 'dependencies'],
+}))
+/* => object:
+{
+  version: '1.0.0',
+  name: 'my-awesome-project',
+  dependencies: {
+    'sort-object-keys': '1.0.0',
+    'sort-package-json': '1.0.0'
+  }
+}
+```
+
+
+## Related tools
+
+- [ESLint Rule with Autofix](https://github.com/kellyselden/eslint-plugin-json-files#supported-rules)
+- [Visual Studio Code Extension](https://github.com/unional/vscode-sort-package-json)
+
+## Supported Libraries
 
 - [AVA](https://github.com/avajs/ava)
-- [browserify](http://browserify.org/)
-- [babel](https://babeljs.io/)
-- [eslint](https://eslint.org/)
-- [jest](https://jestjs.io/)
+- [Babel](https://babeljs.io/)
+- [Browserify](http://browserify.org/)
+- [ESLint](https://eslint.org/)
 - [Istanbul](https://istanbul.js.org/)
+- [Jest](https://jestjs.io/)
 - [Mocha](https://mochajs.org/)
 - [node-pre-gyp](https://github.com/mapbox/node-pre-gyp/)
-- [xo](https://github.com/xojs/xo)
-- [prettier](https://prettier.io/)
+- [Prettier](https://prettier.io/)
+- [xojs](https://github.com/xojs/xo)
 
-### Automatically Sort
+## 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:
-```js
+The package.json file can be sorted automatically before committing, install `husky` and `lint-staged` and add the following to your `package.json` file:
+
+```json
 {
   "husky": {
     "hooks": {
@@ -136,25 +182,24 @@ The package.json file can be sorted automatically before committing, install `hu
 }
 ```
 
-### PFAQ: Potential Frequently Asked Questions
+## PFAQ: Potential Frequently Asked Questions
 
-#### How does it sort?
+### How does it sort?
 
 It sorts using [`sort-object-keys`](http://github.com/keithamus/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](./index.js). It sorts sub-keys too - sometimes by a well-known order, other times alphabetically. The initial order was derived from the [package.json docs](https://docs.npmjs.com/files/package.json) with a few extras added for good measure.
 
-#### It doesn't sort X?
+### 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?
+### 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)
-
+- 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?!
+### 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?