配置

🌐 Configuration

Oxfmt 开箱即用，但大多数团队会提交一个配置文件，以保持本地运行、编辑器和持续集成中的格式一致性。

🌐 Oxfmt works out of the box, but most teams commit a configuration file to keep formatting consistent across local runs, editors, and CI.

本页面侧重于项目配置：格式化选项、忽略模式和实验性功能。

🌐 This page focuses on project configuration: formatting options, ignore patterns, and experimental features.

创建配置文件

🌐 Create a config file

在当前目录生成一个初始配置：

🌐 To generate a starter config in the current directory:

oxfmt --init

Oxfmt 会自动从当前目录开始向上查找 .oxfmtrc.json 或 .oxfmtrc.jsonc。你也可以显式地传递配置文件：

🌐 Oxfmt automatically looks for .oxfmtrc.json or .oxfmtrc.jsonc starting from the current directory and walking up the tree. You can also pass a config explicitly:

oxfmt -c path/to/yourconfig.json

一个最小配置如下所示：

🌐 A minimal configuration looks like this:

.oxfmtrc.json

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "printWidth": 80
}

配置文件格式

🌐 Configuration file format

配置文件是一个 JSON 对象。最常见的顶层字段有：

🌐 A configuration file is a JSON object. The most common top-level fields are:

• printWidth：行宽限制（默认：100）
• tabWidth：每个缩进级别的空格数（默认：2）
• useTabs：使用制表符代替空格（默认：false）
• semi：添加分号（默认：是）
• singleQuote：使用单引号（默认：false）
• trailingComma：多行结构中的尾随逗号（默认值：“all”）
• ignorePatterns：用于排除格式化的通配符模式
• experimentalSortImports：配置导入排序（默认禁用）
• experimentalSortPackageJson：配置 package.json 排序（默认启用）
• experimentalTailwindcss：配置 Tailwind 类排序（默认禁用）

有关字段的完整列表，请参阅 配置文件参考。

🌐 For a complete list of fields, see the Config file reference.

JSON 架构

🌐 JSON schema

为编辑器验证和自动补齐添加 $schema 字段：

🌐 Add a $schema field for editor validation and autocomplete:

.oxfmtrc.json

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json"
}

.editorconfig

Oxfmt 读取这些 .editorconfig 属性：

🌐 Oxfmt reads these .editorconfig properties:

• end_of_line → endOfLine
• indent_style → useTabs
• indent_size → tabWidth
• max_line_length → printWidth
• insert_final_newline → insertFinalNewline

支持根部分和基于全局的重写。

🌐 Both root section and glob-based overrides are supported.

[*]
indent_size = 4

[*.{js,ts}]
indent_size = 2

Oxfmt 仅使用当前目录中最近的 .editorconfig：

🌐 Oxfmt uses only the nearest .editorconfig from the current directory:

• root = true 不被尊重
• 嵌套的 .editorconfig 文件未被合并

优先权

🌐 Precedence

选项按顺序应用（从最低到最高优先级）：

🌐 Options are applied in order (lowest to highest priority):

1. 默认值
2. .oxfmtrc.json(c) 根选项
3. .oxfmtrc.json(c) overrides 选项
4. 对于未设置的字段，回退到 .editorconfig 支持的选项

Oxfmt 特定选项

🌐 Oxfmt-specific options

insertFinalNewline

控制是否在格式化后的文件末尾添加换行符。默认值为 true。

🌐 Controls whether a final newline is added to formatted files. Defaults to true.

这是一个经常被请求的 Prettier 功能，因为某些环境（例如 Salesforce）会去掉结尾的换行符。

🌐 This is a frequently requested Prettier feature, as some environments (e.g., Salesforce) strip trailing newlines.

printWidth

Oxfmt 默认使用 printWidth: 100（Prettier 使用 80）。原因如下：

🌐 Oxfmt defaults to printWidth: 100 (Prettier uses 80). Reasons:

• 由于类型注解，TypeScript 代码更长
• 导入语句通常有许多指定符
• 现代屏幕更宽
• 更少的换行意味着更少的语言模型令牌

匹配 Prettier 的默认设置：

🌐 To match Prettier's default:

.oxfmtrc.json

{
  "printWidth": 80
}

下一步

🌐 Next steps

• 忽略文件：忽略文件和模式，以及 .gitignore 和 .prettierignore 工作流程。
• 内联忽略注释：针对特定代码的内联抑制。
• 配置文件参考：完整的模式和字段文档。
• CLI 参考：完整的标志列表。