From fca50c313dab00e22fab311297c4fca407e28809 Mon Sep 17 00:00:00 2001 From: neverland Date: Mon, 3 Aug 2026 16:15:11 +0800 Subject: [PATCH] docs: add formatting guide --- website/docs/en/guide/_meta.json | 13 +- website/docs/en/guide/cli/fmt.mdx | 69 +++------- website/docs/en/guide/configuration.mdx | 18 +-- website/docs/en/guide/formatting.mdx | 168 ++++++++++++++++++++++++ website/docs/zh/guide/_meta.json | 13 +- website/docs/zh/guide/cli/fmt.mdx | 69 +++------- website/docs/zh/guide/configuration.mdx | 18 +-- website/docs/zh/guide/formatting.mdx | 168 ++++++++++++++++++++++++ 8 files changed, 388 insertions(+), 148 deletions(-) create mode 100644 website/docs/en/guide/formatting.mdx create mode 100644 website/docs/zh/guide/formatting.mdx diff --git a/website/docs/en/guide/_meta.json b/website/docs/en/guide/_meta.json index 0714b8b..c637e78 100644 --- a/website/docs/en/guide/_meta.json +++ b/website/docs/en/guide/_meta.json @@ -24,13 +24,18 @@ }, { "type": "file", - "name": "monorepo", - "label": "Monorepo" + "name": "testing", + "label": "Testing" }, { "type": "file", - "name": "testing", - "label": "Testing" + "name": "formatting", + "label": "Formatting" + }, + { + "type": "file", + "name": "monorepo", + "label": "Monorepo" }, { "type": "dir-section-header", diff --git a/website/docs/en/guide/cli/fmt.mdx b/website/docs/en/guide/cli/fmt.mdx index 506037c..fd1eb63 100644 --- a/website/docs/en/guide/cli/fmt.mdx +++ b/website/docs/en/guide/cli/fmt.mdx @@ -1,6 +1,6 @@ # fmt -The `rs fmt` command is built on [Prettier](https://prettier.io/). It processes files in parallel by default and uses the high-performance [Yuku](https://yuku.fyi/) parser for JavaScript and TypeScript, providing better performance than using Prettier directly. +The `rs fmt` command formats files or checks whether they are formatted. For detailed usage, see [Formatting](../formatting). ## Usage @@ -8,74 +8,35 @@ The `rs fmt` command is built on [Prettier](https://prettier.io/). It processes rs fmt [options] [files/globs...] ``` -Pass files, directories, or glob patterns to select what to format. When no inputs are provided, `rs fmt` formats the current directory. `rs format` is an alias for `rs fmt`. - -## Options - -| Option | Description | -| ---------------------------- | ----------------------------------------------------------------------------------- | -| `--write` | Write formatted files in place. This is the default mode. | -| `--check` | Check formatting without writing files. Exits with code 1 when files are different. | -| `--list-different` | Print only unformatted paths. Exits with code 1 when files are different. | -| `--parallel-workers ` | Set the maximum number of formatting workers. | -| `-h, --help` | Display usage and option information. | - -`--write`, `--check`, and `--list-different` are mutually exclusive. +Pass files, directories, or glob patterns to choose what to format. When no paths are provided, `rs fmt` formats the current directory. Examples: ```bash -# Format the current directory in place +# Format files in the current directory rs fmt # Format specific files and directories rs fmt src package.json -# Include and exclude files with quoted globs -rs fmt "src/**/*.{js,ts}" "!src/generated/**" - # Check formatting in CI rs fmt --check ``` -## File discovery - -Directory and glob discovery follows `.gitignore` files, skips binary files, and does not traverse version-control directories or `node_modules`. Files for which Prettier cannot infer a parser are skipped. - -Use [`ignorePatterns`](../configuration#define-fmt) for additional project-specific exclusions. Both positive and negative input globs are resolved from the current working directory. - -## Configuration +`rs format` is an alias for `rs fmt`: -Configure formatting through [`define.fmt()`](../configuration#define-fmt) in the [Rstack configuration file](/guide/configuration#configuration-file): - -```ts title="rstack.config.ts" -import { define } from 'rstack'; - -define.fmt({ - printWidth: 100, - singleQuote: true, - sortPackageJson: true, - ignorePatterns: ['dist/**'], - overrides: [ - { - files: '*.md', - options: { - proseWrap: 'always', - }, - }, - ], -}); +```bash +rs format ``` -`define.fmt()` accepts standard [Prettier options](https://prettier.io/docs/options) and the `overrides` field, plus these Rstack options: - -- `ignorePatterns`: Gitignore-compatible patterns relative to the directory containing `rstack.config.ts`. -- `sortPackageJson`: Sort `package.json` fields before formatting. The default value is `false`. - -:::warning Configuration sources - -`rs fmt` does not load Prettier configuration files, `.prettierignore`, or `.editorconfig`. Move those settings and ignore rules into `define.fmt()`. +## Options -::: +| Option | Description | +| ---------------------------- | ----------------------------------------------------------------------------------- | +| `--write` | Write formatted files in place. This is the default mode. | +| `--check` | Check formatting without writing files. Exits with code 1 when files are different. | +| `--list-different` | Print only unformatted paths. Exits with code 1 when files are different. | +| `--parallel-workers ` | Set the maximum number of formatting workers. | +| `-h, --help` | Display usage and option information. | -When using [Prettier plugins](https://prettier.io/docs/plugins), pass each plugin as a package name, file path, or URL. Imported plugin objects are not supported because formatting runs in workers. Package names and relative paths are resolved from the Rstack configuration directory. +> `--write`, `--check`, and `--list-different` are mutually exclusive. diff --git a/website/docs/en/guide/configuration.mdx b/website/docs/en/guide/configuration.mdx index e405a8a..8d6a5cf 100644 --- a/website/docs/en/guide/configuration.mdx +++ b/website/docs/en/guide/configuration.mdx @@ -168,9 +168,7 @@ define.lint(async () => { ### `define.fmt()` \{#define-fmt} -Defines the formatting configuration used by [`rs fmt`](./cli/fmt). Pass the configuration directly, or return it from a synchronous or asynchronous function. - -`define.fmt()` accepts standard [Prettier options](https://prettier.io/docs/options) and the `overrides` field. It also supports `ignorePatterns` for Gitignore-compatible exclusions and `sortPackageJson` for sorting `package.json` fields before formatting. +Defines formatting settings for [`rs fmt`](./cli/fmt). Pass a configuration object directly, or use a synchronous or asynchronous function that returns one. ```ts title="rstack.config.ts" import { define } from 'rstack'; @@ -178,22 +176,10 @@ import { define } from 'rstack'; define.fmt({ printWidth: 100, singleQuote: true, - sortPackageJson: true, - ignorePatterns: ['dist/**'], - overrides: [ - { - files: '*.md', - options: { - proseWrap: 'always', - }, - }, - ], }); ``` -Ignore patterns, override patterns, and relative plugin paths are resolved from the directory containing the Rstack configuration file. Specify Prettier plugins as package names, paths, or URLs rather than imported plugin objects. - -`rs fmt` does not load Prettier configuration files, `.prettierignore`, or `.editorconfig`; keep all formatting options and ignore rules in `define.fmt()`. +For detailed usage, see [Formatting](./formatting). ### `define.staged()` \{#define-staged} diff --git a/website/docs/en/guide/formatting.mdx b/website/docs/en/guide/formatting.mdx new file mode 100644 index 0000000..a6136ce --- /dev/null +++ b/website/docs/en/guide/formatting.mdx @@ -0,0 +1,168 @@ +# Formatting + +import { PackageManagerTabs } from '@rspress/core/theme'; + +Rstack CLI includes a formatter built on [Prettier](https://prettier.io/). Compared with running Prettier directly, `rs fmt` offers better performance in two ways: + +- **Parallel formatting**: `rs fmt` formats files concurrently in a worker pool. +- **Yuku parser**: `rs fmt` uses the high-performance [Yuku](https://yuku.fyi/) parser by default for JavaScript, JSX, and TypeScript files. + +`rs fmt` supports Prettier options and plugins and adds built-in capabilities such as [sorting package.json fields](#sort-package-json). + +## Basic usage + +Run `rs fmt` without file arguments to format files in the current directory and save the changes: + +```bash +rs fmt +``` + +Use `--check` to verify formatting without changing files: + +```bash +rs fmt --check +``` + +See the [`rs fmt` CLI reference](./cli/fmt) for more command-line options. + +## Configuration + +Use [`define.fmt()`](./configuration#define-fmt) in `rstack.config.ts` to set formatting rules. It supports all [Prettier options](https://prettier.io/docs/options): + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.fmt({ + printWidth: 100, + singleQuote: true, +}); +``` + +In addition to Prettier options and `overrides`, Rstack provides two options: + +- [`ignorePatterns`](#ignore-files): exclude files with Gitignore-compatible patterns. +- [`sortPackageJson`](#sort-package-json): sort fields in `package.json` files. The default value is `false`. + +:::warning Prettier configuration files + +`rs fmt` does not read Prettier configuration files, `.prettierignore`, or `.editorconfig`. Keep formatting options and additional ignore rules in `define.fmt()`. + +::: + +## Formatting scope + +`rs fmt` determines the formatting scope from the paths passed on the command line. You can combine the following inputs: + +- **Files**: format only the specified files. +- **Directories**: scan directories recursively and format supported files. +- **Glob patterns**: match multiple paths, and prefix a pattern with `!` to exclude matches. + +When no paths are provided, `rs fmt` formats the current directory. All glob patterns are resolved from the current working directory. Quote them so that `rs fmt`, rather than the shell, expands them: + +```bash +# Format a directory and a file +rs fmt src package.json + +# Format JavaScript and TypeScript files, excluding generated files +rs fmt "src/**/*.{js,ts}" "!src/generated/**" +``` + +When scanning directories or globs, `rs fmt` follows `.gitignore` rules, skips binary files, and does not traverse version-control directories or `node_modules`. It also skips files for which Prettier cannot infer a parser. + +`.gitignore` applies only when scanning directories and globs. It does not exclude files passed explicitly on the command line. To always exclude a file, use [`ignorePatterns`](#ignore-files). + +## Ignore files + +Use `ignorePatterns` to exclude files from formatting: + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.fmt({ + ignorePatterns: ['dist/**', 'coverage/**', '**/generated/**'], +}); +``` + +Patterns follow Gitignore syntax and are resolved relative to the directory containing the Rstack configuration file. Because they are applied after the files are selected, they also exclude files passed explicitly on the command line. + +## Sort package.json fields \{#sort-package-json} + +Enable `sortPackageJson` to sort fields in each selected `package.json` with [`sort-package-json`](https://github.com/keithamus/sort-package-json): + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.fmt({ + sortPackageJson: true, +}); +``` + +## Overrides + +Use the `overrides` field to set options for specific files. Each override supports these fields: + +- `files`: files or glob patterns to match. +- `options`: formatting options applied to matching files. +- `excludeFiles`: optional files or glob patterns to exclude. + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.fmt({ + overrides: [ + { + files: 'docs/**/*.md', + excludeFiles: 'docs/generated/**', + options: { + proseWrap: 'always', + }, + }, + ], +}); +``` + +### Pattern matching + +The `files` and `excludeFiles` patterns are resolved relative to the directory containing `rstack.config.ts`. + +In `files`, a pattern without `/` matches file names at any depth, while a pattern containing `/` matches relative paths. In this example, `*.md` matches Markdown files in any directory, while `scripts/**/*.js` matches paths relative to the configuration directory: + +```ts +define.fmt({ + overrides: [ + { files: '*.md', options: { proseWrap: 'always' } }, + { files: 'scripts/**/*.js', options: { singleQuote: true } }, + ], +}); +``` + +### Merge order + +When multiple overrides match, they are applied in declaration order, so later values take precedence. Here, `README.md` matches both overrides, so the final `printWidth` is `80`: + +```ts +define.fmt({ + overrides: [ + { files: '*.md', options: { printWidth: 100 } }, + { files: 'README.md', options: { printWidth: 80 } }, + ], +}); +``` + +## Prettier plugins + +To add formatting capabilities that are not built into Rstack, install the corresponding [Prettier plugin](https://prettier.io/docs/plugins) and add it to `plugins`. Plugins can be referenced by package name, file path, or URL. Package names and relative paths are resolved from the directory containing the Rstack configuration file. + +Because `rs fmt` loads plugins in workers, plugin objects cannot be passed directly. Reference each plugin by package name, path, or URL instead. For example, install and enable [`prettier-plugin-tailwindcss`](https://github.com/tailwindlabs/prettier-plugin-tailwindcss): + + + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.fmt({ + plugins: ['prettier-plugin-tailwindcss'], +}); +``` + +To enable a plugin only for specific files, add `plugins` to the `options` of an [`overrides`](#overrides) entry. diff --git a/website/docs/zh/guide/_meta.json b/website/docs/zh/guide/_meta.json index 8d03c9c..5b1c69d 100644 --- a/website/docs/zh/guide/_meta.json +++ b/website/docs/zh/guide/_meta.json @@ -24,13 +24,18 @@ }, { "type": "file", - "name": "monorepo", - "label": "Monorepo" + "name": "testing", + "label": "测试" }, { "type": "file", - "name": "testing", - "label": "测试" + "name": "formatting", + "label": "格式化" + }, + { + "type": "file", + "name": "monorepo", + "label": "Monorepo" }, { "type": "dir-section-header", diff --git a/website/docs/zh/guide/cli/fmt.mdx b/website/docs/zh/guide/cli/fmt.mdx index 8a6f4b2..848dee2 100644 --- a/website/docs/zh/guide/cli/fmt.mdx +++ b/website/docs/zh/guide/cli/fmt.mdx @@ -1,6 +1,6 @@ # fmt -`rs fmt` 命令底层基于 [Prettier](https://prettier.io/)。它默认并行处理文件，并使用高性能的 [Yuku](https://yuku.fyi/) 解析器处理 JavaScript 和 TypeScript，相比于直接使用 Prettier 具有更好的性能。 +`rs fmt` 命令用于格式化文件或检查文件格式。详细用法请参考[格式化](../formatting)指南。 ## 用法 \{#usage} @@ -8,74 +8,35 @@ rs fmt [options] [files/globs...] ``` -可以传入文件、目录或 glob 模式来指定格式化范围。未传入目标时，`rs fmt` 会格式化当前目录。`rs format` 是 `rs fmt` 的别名。 - -## 选项 \{#options} - -| 选项 | 说明 | -| ---------------------------- | ----------------------------------------------------- | -| `--write` | 将格式化结果写回文件。这是默认模式。 | -| `--check` | 检查格式但不写入文件；存在格式差异时以状态码 1 退出。 | -| `--list-different` | 仅输出未格式化的路径；存在格式差异时以状态码 1 退出。 | -| `--parallel-workers ` | 设置格式化 worker 的最大数量。 | -| `-h, --help` | 显示命令用法和选项。 | - -`--write`、`--check` 和 `--list-different` 不能同时使用。 +可以传入文件、目录或 glob 模式来指定格式化范围。不传入路径时，`rs fmt` 会格式化当前目录。 示例： ```bash -# 就地格式化当前目录 +# 格式化当前目录中的文件 rs fmt # 格式化指定文件和目录 rs fmt src package.json -# 使用带引号的 glob 包含和排除文件 -rs fmt "src/**/*.{js,ts}" "!src/generated/**" - # 在 CI 中检查格式 rs fmt --check ``` -## 文件发现 \{#file-discovery} - -扫描目录或 glob 时，`rs fmt` 会遵循 `.gitignore`、跳过二进制文件，并且不会遍历版本控制目录或 `node_modules`。Prettier 无法推断 parser 的文件也会被跳过。 - -如需添加项目专属的排除规则，请使用 [`ignorePatterns`](../configuration#define-fmt)。传入的正向和反向 glob 都基于当前工作目录解析。 - -## 配置 \{#configuration} +`rs format` 是 `rs fmt` 的别名： -在 [Rstack 配置文件](/guide/configuration#configuration-file)中通过 [`define.fmt()`](../configuration#define-fmt) 配置格式化： - -```ts title="rstack.config.ts" -import { define } from 'rstack'; - -define.fmt({ - printWidth: 100, - singleQuote: true, - sortPackageJson: true, - ignorePatterns: ['dist/**'], - overrides: [ - { - files: '*.md', - options: { - proseWrap: 'always', - }, - }, - ], -}); +```bash +rs format ``` -`define.fmt()` 支持标准的 [Prettier 选项](https://prettier.io/docs/options)和 `overrides` 字段，并额外提供以下 Rstack 选项： - -- `ignorePatterns`：相对于 `rstack.config.ts` 所在目录的 Gitignore 兼容模式。 -- `sortPackageJson`：格式化前对 `package.json` 字段排序，默认值为 `false`。 - -:::warning 配置来源 - -`rs fmt` 不会加载 Prettier 配置文件、`.prettierignore` 或 `.editorconfig`。请将其中的配置和忽略规则迁移到 `define.fmt()`。 +## 选项 \{#options} -::: +| 选项 | 说明 | +| ---------------------------- | ----------------------------------------------------- | +| `--write` | 将格式化结果写回文件。这是默认模式。 | +| `--check` | 检查格式但不写入文件；存在格式差异时以状态码 1 退出。 | +| `--list-different` | 仅输出未格式化的路径；存在格式差异时以状态码 1 退出。 | +| `--parallel-workers ` | 设置格式化 worker 的最大数量。 | +| `-h, --help` | 显示命令用法和选项。 | -使用 [Prettier 插件](https://prettier.io/docs/plugins)时，需要将插件指定为包名、文件路径或 URL。由于格式化在 worker 中运行，因此不支持传入已导入的插件对象。包名和相对路径会基于 Rstack 配置文件所在目录解析。 +> `--write`、`--check` 和 `--list-different` 不能同时使用。 diff --git a/website/docs/zh/guide/configuration.mdx b/website/docs/zh/guide/configuration.mdx index f8d4a75..13fb7cd 100644 --- a/website/docs/zh/guide/configuration.mdx +++ b/website/docs/zh/guide/configuration.mdx @@ -168,9 +168,7 @@ define.lint(async () => { ### `define.fmt()` \{#define-fmt} -定义 [`rs fmt`](./cli/fmt) 使用的格式化配置。可以直接传入配置，也可以通过同步或异步函数返回配置。 - -`define.fmt()` 支持标准的 [Prettier 选项](https://prettier.io/docs/options) 和 `overrides` 字段。此外，还可以通过 `ignorePatterns` 配置 Gitignore 兼容的排除规则，并通过 `sortPackageJson` 在格式化前对 `package.json` 字段排序。 +定义 [`rs fmt`](./cli/fmt) 的格式化配置。可以直接传入配置对象，也可以传入返回配置对象的同步或异步函数。 ```ts title="rstack.config.ts" import { define } from 'rstack'; @@ -178,22 +176,10 @@ import { define } from 'rstack'; define.fmt({ printWidth: 100, singleQuote: true, - sortPackageJson: true, - ignorePatterns: ['dist/**'], - overrides: [ - { - files: '*.md', - options: { - proseWrap: 'always', - }, - }, - ], }); ``` -忽略模式、override 模式和插件相对路径都基于 Rstack 配置文件所在目录解析。Prettier 插件需要指定为包名、路径或 URL，不能传入已导入的插件对象。 - -`rs fmt` 不会加载 Prettier 配置文件、`.prettierignore` 或 `.editorconfig`；请将所有格式化选项和忽略规则集中在 `define.fmt()` 中。 +详细用法请参考[格式化](./formatting)指南。 ### `define.staged()` \{#define-staged} diff --git a/website/docs/zh/guide/formatting.mdx b/website/docs/zh/guide/formatting.mdx new file mode 100644 index 0000000..526038e --- /dev/null +++ b/website/docs/zh/guide/formatting.mdx @@ -0,0 +1,168 @@ +# 格式化 + +import { PackageManagerTabs } from '@rspress/core/theme'; + +Rstack CLI 提供了基于 [Prettier](https://prettier.io/) 的格式化工具。相比直接使用 Prettier，`rs fmt` 的性能更好，主要得益于以下两点： + +- **并行格式化**：`rs fmt` 通过 worker 池并行格式化文件。 +- **Yuku 解析器**：默认使用高性能的 [Yuku](https://yuku.fyi/) 解析器处理 JavaScript、JSX 和 TypeScript 文件。 + +`rs fmt` 兼容 Prettier 的选项和插件，并提供更多内置能力，例如支持[排序 package.json 字段](#sort-package-json)。 + +## 基本用法 \{#basic-usage} + +直接运行 `rs fmt`，即可格式化当前目录中的文件并保存修改： + +```bash +rs fmt +``` + +使用 `--check` 检查文件是否已格式化，而不修改文件： + +```bash +rs fmt --check +``` + +更多命令行选项请参考 [`rs fmt` CLI 文档](./cli/fmt)。 + +## 配置 \{#configuration} + +在 `rstack.config.ts` 中使用 [`define.fmt()`](./configuration#define-fmt) 设置格式化规则。它支持所有的 [Prettier 选项](https://prettier.io/docs/options)： + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.fmt({ + printWidth: 100, + singleQuote: true, +}); +``` + +除了 Prettier 选项和 `overrides`，Rstack 还提供两个选项： + +- [`ignorePatterns`](#ignore-files)：使用兼容 Gitignore 的模式排除文件。 +- [`sortPackageJson`](#sort-package-json)：对 `package.json` 中的字段排序，默认值为 `false`。 + +:::warning Prettier 配置文件 + +`rs fmt` 不会读取 Prettier 配置文件、`.prettierignore` 或 `.editorconfig`。请在 `define.fmt()` 中设置格式化选项和额外的忽略规则。 + +::: + +## 格式化范围 \{#formatting-scope} + +`rs fmt` 根据命令行中传入的路径确定格式化范围。以下输入可以组合使用： + +- **文件**：只格式化指定文件。 +- **目录**：递归扫描目录并格式化支持的文件。 +- **glob 模式**：匹配多个路径，并通过以 `!` 开头的模式排除匹配结果。 + +不传入路径时，`rs fmt` 默认格式化当前目录。所有 glob 模式都基于当前工作目录解析。请为 glob 添加引号，避免它们被 shell 提前展开： + +```bash +# 格式化一个目录和一个文件 +rs fmt src package.json + +# 格式化 JavaScript 和 TypeScript 文件，并排除生成文件 +rs fmt "src/**/*.{js,ts}" "!src/generated/**" +``` + +扫描目录或 glob 时，`rs fmt` 会遵循 `.gitignore` 规则、跳过二进制文件，并且不会遍历版本控制目录或 `node_modules`。Prettier 无法推断解析器的文件也会被跳过。 + +`.gitignore` 只在扫描目录和 glob 时生效，不会排除命令行中显式传入的文件。如果需要始终排除某个文件，请使用 [`ignorePatterns`](#ignore-files)。 + +## 忽略文件 \{#ignore-files} + +使用 `ignorePatterns` 排除不需要格式化的文件： + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.fmt({ + ignorePatterns: ['dist/**', 'coverage/**', '**/generated/**'], +}); +``` + +这些模式遵循 Gitignore 语法，并且基于 Rstack 配置文件所在的目录解析。由于规则会在确定格式化范围后生效，因此也会排除命令行中显式传入的文件。 + +## 排序 package.json 字段 \{#sort-package-json} + +启用 `sortPackageJson` 后，`rs fmt` 会使用 [`sort-package-json`](https://github.com/keithamus/sort-package-json) 对每个待格式化的 `package.json` 中的字段排序： + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.fmt({ + sortPackageJson: true, +}); +``` + +## 覆盖配置 \{#overrides} + +通过 `overrides` 字段，可以为特定文件单独设置格式化选项。每一项都支持以下字段： + +- `files`：需要应用格式化选项的文件或 glob 模式。 +- `options`：应用于匹配文件的格式化选项。 +- `excludeFiles`：可选，需要从匹配结果中排除的文件或 glob 模式。 + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.fmt({ + overrides: [ + { + files: 'docs/**/*.md', + excludeFiles: 'docs/generated/**', + options: { + proseWrap: 'always', + }, + }, + ], +}); +``` + +### 模式匹配 \{#pattern-matching} + +`files` 和 `excludeFiles` 模式都基于 `rstack.config.ts` 所在目录解析。 + +在 `files` 中，不包含 `/` 的模式会匹配任意深度的文件名，包含 `/` 的模式则匹配相对路径。下面示例中的 `*.md` 会匹配任意目录中的 Markdown 文件，而 `scripts/**/*.js` 会匹配相对于 Rstack 配置文件所在目录的路径： + +```ts +define.fmt({ + overrides: [ + { files: '*.md', options: { proseWrap: 'always' } }, + { files: 'scripts/**/*.js', options: { singleQuote: true } }, + ], +}); +``` + +### 合并顺序 \{#merge-order} + +如果同一文件匹配多条 override 规则，Rstack 会按声明顺序合并配置，后面的值优先。下面的 `README.md` 会同时匹配两条规则，因此最终的 `printWidth` 为 `80`： + +```ts +define.fmt({ + overrides: [ + { files: '*.md', options: { printWidth: 100 } }, + { files: 'README.md', options: { printWidth: 80 } }, + ], +}); +``` + +## Prettier 插件 \{#prettier-plugins} + +如果需要使用 Rstack 未内置的格式化能力，可以安装相应的 [Prettier 插件](https://prettier.io/docs/plugins)，并添加到 `plugins` 中。插件支持通过包名、文件路径或 URL 引用，其中包名和相对路径基于 Rstack 配置文件所在的目录解析。 + +由于 `rs fmt` 会在 worker 中加载插件，因此不支持直接传入插件对象。请通过包名、路径或 URL 引用插件。例如，安装并启用 [`prettier-plugin-tailwindcss`](https://github.com/tailwindlabs/prettier-plugin-tailwindcss)： + + + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.fmt({ + plugins: ['prettier-plugin-tailwindcss'], +}); +``` + +如果只需要为特定文件启用插件，可以在 [`overrides`](#overrides) 的 `options` 中配置 `plugins`。