Update docs to encourage user import plugin themself (#18411)

This commit is contained in:
fisker Cheung authored and GitHub committed 2025-12-06 14:43:36 +08:00
1 parent 374138ac6b
commit d8bf3989bd
17 files changed
+214 -181

No files matched your search

-12
View File
@@ -1,12 +0,0 @@
overrides:
- files: "**/*.{js,mjs,cjs}"
options:
parser: meriyah
- files: "bin/prettier.cjs"
options:
trailingComma: none
- files:
- ".vscode/*.json"
- "tsconfig.json"
options:
parser: jsonc
+2 -2
View File
@@ -78,12 +78,12 @@ define([
```js
const prettier = require("prettier/standalone");
const plugins = [require("prettier/plugins/graphql")];
const prettierPluginGraphql = require("prettier/plugins/graphql");
(async () => {
const formatted = await prettier.format("type Query { hello: String }", {
parser: "graphql",
plugins,
plugins: [prettierPluginGraphql],
});
})();
```
+13 -23
View File
@@ -43,7 +43,7 @@ NODE_OPTIONS="--experimental-strip-types" prettier . --write
JSON:
```json
```json title=".prettierrc.json or .prettierrc"
{
"trailingComma": "es5",
"tabWidth": 4,
@@ -54,9 +54,7 @@ JSON:
JS (ES Modules):
```js
// prettier.config.js, .prettierrc.js, prettier.config.mjs, or .prettierrc.mjs
```js title="prettier.config.mjs, .prettierrc.mjs, prettier.config.js, or .prettierrc.js"
/**
* @see https://prettier.io/docs/configuration
* @type {import("prettier").Config}
@@ -73,9 +71,7 @@ export default config;
JS (CommonJS):
```js
// prettier.config.js, .prettierrc.js, prettier.config.cjs, or .prettierrc.cjs
```js title="prettier.config.cjs, .prettierrc.cjs, prettier.config.js, or .prettierrc.js"
/**
* @see https://prettier.io/docs/configuration
* @type {import("prettier").Config}
@@ -92,9 +88,7 @@ module.exports = config;
TypeScript (ES Modules):
```ts
// prettier.config.ts, .prettierrc.ts, prettier.config.mts, or .prettierrc.mts
```ts title="prettier.config.mts, .prettierrc.mts, prettier.config.ts, or .prettierrc.ts"
import { type Config } from "prettier";
const config: Config = {
@@ -106,9 +100,7 @@ export default config;
TypeScript (CommonJS):
```ts
// prettier.config.ts, .prettierrc.ts, prettier.config.cts, or .prettierrc.cts
```ts title="prettier.config.cts, .prettierrc.cts, prettier.config.ts, or .prettierrc.ts"
import { type Config } from "prettier";
const config: Config = {
@@ -120,8 +112,7 @@ module.exports = config;
YAML:
```yaml
# .prettierrc or .prettierrc.yaml
```yaml title=".prettierrc, .prettierrc.yml, or .prettierrc.yaml"
trailingComma: "es5"
tabWidth: 4
semi: false
@@ -130,8 +121,7 @@ singleQuote: true
TOML:
```toml
# .prettierrc.toml
```toml title=".prettierrc.toml"
trailingComma = "es5"
tabWidth = 4
semi = false
@@ -146,7 +136,7 @@ Prettier borrows ESLint’s [override format](https://eslint.org/docs/latest/use
JSON:
```json
```json title=".prettierrc"
{
"semi": false,
"overrides": [
@@ -168,7 +158,7 @@ JSON:
YAML:
```yaml
```yaml title=".prettierrc"
semi: false
overrides:
- files: "*.test.js"
@@ -189,7 +179,7 @@ By default, Prettier automatically infers which parser to use based on the input
For example, to get Prettier to format its own `.prettierrc` file, you can do:
```json
```json title=".prettierrc"
{
"overrides": [
{
@@ -202,7 +192,7 @@ For example, to get Prettier to format its own `.prettierrc` file, you can do:
You can also switch to the `flow` parser instead of the default `babel` for .js files:
```json
```json title=".prettierrc"
{
"overrides": [
{
@@ -233,7 +223,7 @@ Unlike the EditorConfig spec, the search for `.editorconfig` file will stop on t
Here’s an annotated description of how different properties map to Prettier’s behavior:
```ini
```ini title=".editorconfig"
# Stop the editor from looking for .editorconfig files in the parent directories
# root = true
@@ -254,7 +244,7 @@ max_line_length = 80
Here’s a copy+paste-ready `.editorconfig` file if you use the default options:
```ini
```ini title=".editorconfig"
[*]
charset = utf-8
insert_final_newline = true
+6 -6
View File
@@ -58,15 +58,15 @@ For example:
matrix(
1, 0, 0,
0, 1, 0,
0, 0, 1
)
0, 0, 1,
);
// prettier-ignore
matrix(
1, 0, 0,
0, 1, 0,
0, 0, 1
)
0, 0, 1,
);
```
will be transformed to:
@@ -78,8 +78,8 @@ matrix(1, 0, 0, 0, 1, 0, 0, 0, 1);
matrix(
1, 0, 0,
0, 1, 0,
0, 0, 1
)
0, 0, 1,
);
```
## JSX
+4 -1
View File
@@ -13,11 +13,13 @@ Prettier is an opinionated code formatter with support for:
- [TypeScript](https://www.typescriptlang.org/)
- CSS, [Less](https://lesscss.org/), and [SCSS](https://sass-lang.com)
- [HTML](https://en.wikipedia.org/wiki/HTML)
- [Ember/Handlebars](https://handlebarsjs.com/)
- [Ember/Handlebars](https://emberjs.com/)
- [JSON](https://json.org/)
- [GraphQL](https://graphql.org/)
- [Markdown](https://commonmark.org/), including [GFM](https://github.github.com/gfm/) and [MDX v1](https://mdxjs.com/)
- [YAML](https://yaml.org/)
- [Lightning Web Components (LWC)](https://developer.salesforce.com/developer-centers/lightning-web-components)
- [MJML](https://mjml.io/)
It removes all original styling[\*](#footnotes) and ensures that all outputted code conforms to a consistent style. (See this [blog post](https://jlongster.com/A-Prettier-Formatter))
@@ -25,6 +27,7 @@ Prettier takes your code and reprints it from scratch by taking the line length
For example, take the following code:
<!-- prettier-ignore -->
```js
foo(arg1, arg2, arg3, arg4);
```
+4 -4
View File
@@ -12,28 +12,28 @@ First, install Prettier locally:
<TabItem value="npm">
```bash
npm install --save-dev --save-exact prettier
npm install --save-dev --save-exact prettier@%PRETTIER_VERSION%
```
</TabItem>
<TabItem value="yarn">
```bash
yarn add --dev --exact prettier
yarn add --dev --exact prettier@%PRETTIER_VERSION%
```
</TabItem>
<TabItem value="pnpm">
```bash
pnpm add --save-dev --save-exact prettier
pnpm add --save-dev --save-exact prettier@%PRETTIER_VERSION%
```
</TabItem>
<TabItem value="bun">
```bash
bun add --dev --exact prettier
bun add --dev --exact prettier@%PRETTIER_VERSION%
```
</TabItem>
+1 -1
View File
@@ -27,7 +27,7 @@ So why are there any options at all?
Options that are easier to motivate include:
- `--trailing-comma es5` lets you use trailing commas in most environments without having to transpile (trailing function commas were added in ES2017).
- `--trailing-comma=es5` lets you use trailing commas in most environments without having to transpile (trailing function commas were added in ES2017).
- `--prose-wrap` is important to support all quirky Markdown renderers in the wild.
- `--html-whitespace-sensitivity` is needed due to the unfortunate whitespace rules of HTML.
- `--end-of-line` makes it easier for teams to keep CRLFs out of their git repositories.
+21 -13
View File
@@ -24,18 +24,28 @@ You can load plugins with:
- The [API](api.md), via the `plugins` options:
```js
import * as prettierPluginFoo from "prettier-plugin-foo";
await prettier.format("code", {
parser: "foo",
plugins: ["prettier-plugin-foo"],
plugins: [prettierPluginFoo],
});
```
- The [Configuration File](configuration.md):
```json
{
"plugins": ["prettier-plugin-foo"]
}
```js title="prettier.config.mjs"
import * as prettierPluginFoo from "prettier-plugin-foo";
/**
* @see https://prettier.io/docs/configuration
* @type {import("prettier").Config}
*/
const config = {
plugins: [prettierPluginFoo],
};
export default config;
```
Strings provided to `plugins` are ultimately passed to [`import()` expression](https://nodejs.org/api/esm.html#import-expressions), so you can provide a module/package name, a path, or anything else `import()` takes.
@@ -520,16 +530,15 @@ The `--debug-print-comments` CLI flag can help with debugging comment attachment
Example:
```js
export default {
// ... plugin implementation
options: {
// ... plugin implementation
export const options = {
openingBraceNewLine: {
type: "boolean",
category: "Global",
default: true,
description: "Move open brace for code blocks onto new line.",
},
},
};
```
@@ -538,11 +547,10 @@ export default {
If your plugin requires different default values for some of Prettier’s core options, you can specify them in `defaultOptions`:
```js
export default {
// ... plugin implementation
defaultOptions: {
// ... plugin implementation
export const defaultOptions = {
tabWidth: 4,
},
};
```
+7 -7
View File
@@ -33,7 +33,7 @@ Install it along with [simple-git-hooks](https://github.com/toplenboren/simple-g
```bash
npm install --save-dev simple-git-hooks pretty-quick
echo '{\n "pre-commit": "npx pretty-quick --staged"\n}\n' > .simple-git-hooks.json
node --eval "fs.writeFileSync('.simple-git-hooks.json',JSON.stringify({'pre-commit':'npx pretty-quick --staged'},undefined,2)+'\n')"
npx simple-git-hooks
```
@@ -42,7 +42,7 @@ npx simple-git-hooks
```bash
yarn add --dev simple-git-hooks pretty-quick
echo '{\n "pre-commit": "yarn pretty-quick --staged"\n}\n' > .simple-git-hooks.json
node --eval "fs.writeFileSync('.simple-git-hooks.json',JSON.stringify({'pre-commit':'yarn pretty-quick --staged'},undefined,2)+'\n')"
yarn simple-git-hooks
```
@@ -51,7 +51,7 @@ yarn simple-git-hooks
```bash
pnpm add --save-dev simple-git-hooks pretty-quick
echo '{\n "pre-commit": "pnpm pretty-quick --staged"\n}\n' > .simple-git-hooks.json
node --eval "fs.writeFileSync('.simple-git-hooks.json',JSON.stringify({'pre-commit':'pnpm pretty-quick --staged'},undefined,2)+'\n')"
pnpm simple-git-hooks
```
@@ -60,7 +60,7 @@ pnpm simple-git-hooks
```bash
bun add --dev simple-git-hooks pretty-quick
echo '{\n "pre-commit": "bun pretty-quick --staged"\n}\n' > .simple-git-hooks.json
node --eval "fs.writeFileSync('.simple-git-hooks.json',JSON.stringify({'pre-commit':'bun pretty-quick --staged'},undefined,2)+'\n')"
bun simple-git-hooks
```
@@ -82,7 +82,7 @@ dotnet husky add pre-commit
after installation you can add prettier task to the `task-runner.json`.
```json
```json title="task-runner.json"
{
"command": "npx",
"args": ["prettier", "--ignore-unknown", "--write", "${staged}"],
@@ -150,7 +150,7 @@ To read about how git-format-staged works see [Automatic Code Formatting for Par
Alternately you can save this script as `.git/hooks/pre-commit` and give it execute permission:
```sh
```sh title=".git/hooks/pre-commit"
#!/bin/sh
FILES=$(git diff --cached --name-only --diff-filter=ACMR | sed 's| |\\ |g')
[ -z "$FILES" ] && exit 0
@@ -168,7 +168,7 @@ If git is reporting that your prettified files are still modified after committi
Add something like the following to `.git/hooks/post-commit`:
```sh
```sh title=".git/hooks/post-commit"
#!/bin/sh
git update-index -g
```
+27 -54
View File
@@ -31,7 +31,7 @@ prettier-config/
Example `package.json`:
```json
```json title="package.json"
{
"name": "@username/prettier-config",
"version": "1.0.0",
@@ -44,13 +44,20 @@ Example `package.json`:
},
"peerDependencies": {
"prettier": ">=3.0.0"
},
"devDependencies": {
"prettier": "%PRETTIER_VERSION%"
}
}
```
`index.js` is where you put the shared configuration. This file just exports a [regular prettier configuration](./configuration.md) with the same syntax and same options:
```js
```js title="index.js"
/**
* @see https://prettier.io/docs/configuration
* @type {import("prettier").Config}
*/
const config = {
trailingComma: "es5",
tabWidth: 4,
@@ -107,7 +114,7 @@ bun add --dev @username/prettier-config
Then, you can reference it in your `package.json`:
```json
```json title="package.json"
{
"name": "my-cool-library",
"version": "1.0.0",
@@ -117,18 +124,19 @@ Then, you can reference it in your `package.json`:
If you don’t want to use `package.json`, you can use any of the supported extensions to export a string, e.g. `.prettierrc`:
```json
```json title=".prettierrc"
"@company/prettier-config"
```
### Extending a Sharable Config
To _extend_ the configuration to overwrite some properties from the shared configuration, import the file in a `.prettierrc.mjs` file and export the modifications, e.g:
To _extend_ the configuration to overwrite some properties from the shared configuration, import the file in a `prettier.config.mjs` file and export the modifications, e.g:
```js
```js title="prettier.config.mjs"
import usernamePrettierConfig from "@username/prettier-config";
/**
* @see https://prettier.io/docs/configuration
* @type {import("prettier").Config}
*/
const config = {
@@ -141,64 +149,26 @@ export default config;
## Other examples
### Using Type Annotation in the Shared Config
You can get type safety and autocomplete support in your shared configuration by using a `jsdoc` type annotation:
```js
/**
* @type {import("prettier").Config}
*/
const config = {
trailingComma: "es5",
tabWidth: 4,
semi: false,
singleQuote: true,
};
export default config;
```
In order to make this work, you have to [install `prettier`](./install.md) for the project.
After that, your `package.json` file should look like this:
```diff
{
"name": "@username/prettier-config",
"version": "1.0.0",
"description": "My personal Prettier config",
"type": "module",
"exports": "./index.js",
"license": "MIT",
"publishConfig": {
"access": "public"
},
"peerDependencies": {
"prettier": ">=3.0.0"
},
+ "devDependencies": {
+ "prettier": "^3.3.3"
+ }
}
```
### Include Plugins in Shareable Configurations
In case you want to use [plugins](./plugins.md) in your shared configuration, you need to declare those plugins in the config file's `plugin` array and as `dependencies` in `package.json`:
```js
// index.js
```js title="index.js"
import * as prettierPluginOxc from "@prettier/plugin-oxc";
/**
* @see https://prettier.io/docs/configuration
* @type {import("prettier").Config}
*/
const config = {
singleQuote: true,
plugins: ["prettier-plugin-xml"],
plugins: [prettierPluginOxc],
};
export default config;
```
```diff
// package.json
```diff title="package.json"
{
"name": "@username/prettier-config",
"version": "1.0.0",
@@ -210,10 +180,13 @@ export default config;
"access": "public"
},
+ "dependencies": {
+ "prettier-plugin-xml": "3.4.1"
+ "@prettier/plugin-oxc": "0.1.2"
+ },
"peerDependencies": {
"prettier": ">=3.0.0"
},
"devDependencies": {
"prettier": "%PRETTIER_VERSION%"
}
}
```
+31 -13
View File
@@ -8,28 +8,46 @@
## Install
```bash
yarn add --dev prettier @prettier/plugin-hermes
yarn add --dev --exact prettier @prettier/plugin-hermes
```
## Usage
Create or modify your [prettier configuration file](https://prettier.io/docs/en/configuration) to use the plugin:
```yaml
plugins:
- "@prettier/plugin-hermes"
```js
// prettier.config.mjs
import * as prettierPluginHermes from "@prettier/plugin-hermes";
/** @type {import("prettier").Config} */
const config = {
plugins: [prettierPluginHermes],
};
export default config;
```
**Requires prettier >= 3.6**
**Requires prettier>=3.6.0**
Or config explicitly
```yaml
overrides:
- files:
- "**/*.{js.flow,js,mjs,cjs}"
options:
plugins:
- "@prettier/plugin-hermes"
parser: hermes
```js
// prettier.config.mjs
import * as prettierPluginHermes from "@prettier/plugin-hermes";
/**
* @see https://prettier.io/docs/configuration
* @type {import("prettier").Config}
*/
const config = {
overrides: [
{
files: ["**/*.{js.flow,js,mjs,cjs}"],
parser: "hermes",
plugins: [prettierPluginHermes],
},
],
};
export default config;
```
+39 -19
View File
@@ -8,34 +8,54 @@
## Install
```bash
yarn add --dev prettier @prettier/plugin-oxc
yarn add --dev --exact prettier @prettier/plugin-oxc
```
## Usage
Create or modify your [prettier configuration file](https://prettier.io/docs/en/configuration) to use the plugin:
```yaml
plugins:
- "@prettier/plugin-oxc"
```js
// prettier.config.mjs
import * as prettierPluginOxc from "@prettier/plugin-oxc";
/**
* @see https://prettier.io/docs/configuration
* @type {import("prettier").Config}
*/
const config = {
plugins: [prettierPluginOxc],
};
export default config;
```
**Requires prettier >= 3.6**
**Requires prettier>=3.6.0**
Or config explicitly
```yaml
overrides:
- files:
- "**/*.{js,mjs,cjs,jsx}"
options:
plugins:
- "@prettier/plugin-oxc"
parser: oxc
- files:
- "**/*.{ts,mts,cts,tsx}"
options:
plugins:
- "@prettier/plugin-oxc"
parser: oxc-ts
```js
// prettier.config.mjs
import * as prettierPluginOxc from "@prettier/plugin-oxc";
/**
* @see https://prettier.io/docs/configuration
* @type {import("prettier").Config}
*/
const config = {
overrides: [
{
files: ["**/*.{js,mjs,cjs,jsx}"],
parser: "oxc",
plugins: [prettierPluginOxc],
},
{
files: ["**/*.{ts,mts,cts,tsx}"],
parser: "oxc-ts",
plugins: [prettierPluginOxc],
},
],
};
export default config;
```
+28
View File
@@ -0,0 +1,28 @@
/**
* @see https://prettier.io/docs/configuration
* @type {import("prettier").Config}
*/
const config = {
overrides: [
{
files: ["**/*.{js,mjs,cjs}"],
options: {
parser: "meriyah",
},
},
{
files: ["bin/prettier.cjs"],
options: {
trailingComma: "none",
},
},
{
files: [".vscode/*.json", "tsconfig.json"],
options: {
parser: "jsonc",
},
},
],
};
export default config;
@@ -4,7 +4,7 @@ import prettier from "../../config/prettier-entry.js";
test("API resolveConfigFile", async () => {
const result = await prettier.resolveConfigFile();
expect(result).toEqual(
url.fileURLToPath(new URL("../../../.prettierrc", import.meta.url)),
url.fileURLToPath(new URL("../../../prettier.config.js", import.meta.url)),
);
});
+25 -23
View File
@@ -2,37 +2,39 @@
image: /images/languages/tools_js.svg
variants:
- "[JSX](https://facebook.github.io/jsx/)"
- "[Flow](https://flow.org)"
- "[TypeScript](https://www.typescriptlang.org)"
- "[JSON](https://json.org)"
- name: HTML
image: /images/languages/tools_html.svg
variants:
- "[Vue](https://vuejs.org)"
- "[Angular](https://angular.io)"
- "[Ember / Handlebars](https://emberjs.com)"
- "[Flow](https://flow.org/)"
- "[TypeScript](https://www.typescriptlang.org/)"
- "[JSON](https://json.org/)"
- name: CSS
image: /images/languages/tools_css.svg
variants:
- "[Less](http://lesscss.org)"
- "[SCSS](https://sass-lang.com)"
- "[`styled-components`](https://styled-components.com) 💅"
- "[`styled-jsx`](https://npmjs.com/styled-jsx)"
- "[Less](http://lesscss.org/)"
- "[SCSS](https://sass-lang.com/)"
- "[`styled-components`](https://styled-components.com/) 💅"
- "[`styled-jsx`](https://npmjs.com/styled-jsx/)"
- name: HTML
image: /images/languages/tools_html.svg
variants:
- "[Vue](https://vuejs.org/)"
- "[Angular](https://angular.io/)"
- "[Ember / Handlebars](https://emberjs.com/)"
- "[Lightning Web Components (LWC)](https://developer.salesforce.com/developer-centers/lightning-web-components)"
- "[MJML](https://mjml.io/)"
- name: YAML
nameLink: https://yaml.org
image: /images/languages/tools_yaml.svg
variants: []
- name: Markdown
image: /images/languages/tools_md.svg
variants:
- "[CommonMark](https://commonmark.org/)"
- "[GitHub-Flavored Markdown](https://github.github.com/gfm/)"
- "[MDX v1](https://mdxjs.com/)"
- name: GraphQL
nameLink: https://graphql.org
image: /images/languages/tools_gql.svg
variants:
- "[GraphQL Schemas](https://graphql.org/learn/schema/)"
- name: Markdown
image: /images/languages/tools_md.svg
variants:
- "[CommonMark](https://commonmark.org)"
- "[GitHub-Flavored Markdown](https://github.github.com/gfm/)"
- "[MDX v1](https://mdxjs.com)"
- name: YAML
nameLink: https://yaml.org
image: /images/languages/tools_yaml.svg
variants: []
- name: Community Plugins
nameLink: ./docs/plugins#community-plugins
image: /images/languages/tools_wip.svg
+4 -2
View File
@@ -22,10 +22,12 @@ await fs.cp(CURRENT_DOCS_DIRECTORY, STABLE_DOCS_DIRECTORY, { recursive: true });
if (process.env.PULL_REQUEST !== "true") {
// Replace version placeholders
await Promise.all(
["browser.md"].map(async (file) => {
["browser.md", "install.md", "sharing-configurations.md"].map(
async (file) => {
file = new URL(file, STABLE_DOCS_DIRECTORY);
await replaceVersionPlaceholder(file, version);
}),
},
),
);
}
@@ -129,6 +129,7 @@ To _extend_ the configuration to overwrite some properties from the shared confi
import usernamePrettierConfig from "@username/prettier-config";
/**
* @see https://prettier.io/docs/configuration
* @type {import("prettier").Config}
*/
const config = {