docs: recommend against eslint-plugin-prettier in formatting guide (typescript-eslint#7639)

JoshuaKGoldberg · Josh-Cena · web-flow · commit 9cb9211cb61b · 2023-09-16T17:31:39.000-04:00
* docs: recommend against eslint-plugin-prettier in formatting guide

* Refer to check

* Update docs/linting/troubleshooting/Formatting.mdx

Co-authored-by: Joshua Chen &lt;sidachen2003@gmail.com&gt;

* newline

---------

Co-authored-by: Joshua Chen &lt;sidachen2003@gmail.com&gt;
diff --git a/docs/linting/troubleshooting/Formatting.mdx b/docs/linting/troubleshooting/Formatting.mdx
@@ -55,6 +55,16 @@ module.exports = {
 
 Note that even if you use a formatter other than `prettier`, you can use `eslint-config-prettier` as it exclusively turns **off** all formatting rules.
 
+#### `eslint-plugin-prettier`
+
+`eslint-config-prettier` is not the same as [`eslint-plugin-prettier`](https://github.com/prettier/eslint-plugin-prettier).
+
+- The _config_ only disables rules from core and other plugins.
+- The _plugin_ loads and runs Prettier inside ESLint.
+
+Running Prettier inside ESLint can be slow: see [Performance Troubleshooting > `eslint-plugin-prettier`](./performance-troubleshooting#eslint-plugin-prettier).
+However, because it doesn't re-implement Prettier's logic in ESLint, the caveats mentioned about using linters for formatting don't apply to `eslint-plugin-prettier` either.
+
 ## ESLint Core and Formatting
 
 Most lint rules fall into one of two to three categories:
diff --git a/docs/linting/troubleshooting/Performance.mdx b/docs/linting/troubleshooting/Performance.mdx
@@ -57,18 +57,20 @@ See our [documentation on formatting](./Formatting.mdx) for more information.
 
 ## `eslint-plugin-prettier`
 
-This plugin surfaces prettier formatting problems at lint time, helping to ensure your code is always formatted.
-However this comes at a quite a large cost - in order to figure out if there is a difference, it has to do a prettier format on every file being linted.
+This plugin surfaces Prettier formatting problems at lint time, helping to ensure your code is always formatted.
+However this comes at a quite a large cost - in order to figure out if there is a difference, it has to do a Prettier format on every file being linted.
 This means that each file will be parsed twice - once by ESLint, and once by Prettier.
 This can add up for large codebases.
 
-Instead of using this plugin, we recommend using prettier's `--list-different` flag to detect if a file has not been correctly formatted.
+Instead of using this plugin, we recommend using Prettier's `--check` flag to detect if a file has not been correctly formatted.
 For example, our CI is setup to run the following command automatically, which blocks PRs that have not been formatted:
 
 ```bash npm2yarn
-npm run prettier --list-different \"./**/*.{ts,mts,cts,tsx,js,mjs,cjs,jsx,json,md,css}\"
+npm run prettier --check .
 ```
 
+See [Prettier's `--check` docs](https://prettier.io/docs/en/cli#--check) for more details.
+
 ## `eslint-plugin-import`
 
 This is another great plugin that we use ourselves in this project.
diff --git a/package.json b/package.json
@@ -27,7 +27,7 @@
     "check-clean-workspace-after-install": "git diff --quiet --exit-code",
     "check-configs": "nx run-many --target=check-configs --parallel",
     "check-docs": "nx run-many --target=check-docs --parallel",
-    "check-format": "prettier --list-different .",
+    "check-format": "prettier --check .",
     "check-spelling": "cspell --config=.cspell.json \"**/*.{md,mdx,ts,mts,cts,js,cjs,mjs,tsx,jsx}\" --no-progress --show-context --show-suggestions",
     "clean": "lerna clean -y && nx run-many --target=clean",
     "format": "prettier --write .",
