从 Prettier 迁移

本指南介绍如何从 Prettier 迁移到 Oxfmt。

WARNING

Oxfmt 处于测试阶段，可能不适合特别复杂的配置。

快速开始

对于简单配置，仅需一条命令即可完成迁移：

npm

$ npm add -D oxfmt@latest && npx oxfmt --migrate=prettier && npx oxfmt

pnpm

$ pnpm add -D oxfmt@latest && pnpm oxfmt --migrate=prettier && pnpm oxfmt

yarn

$ yarn add -D oxfmt@latest && yarn oxfmt --migrate=prettier && yarn oxfmt

bun

$ bun add -D oxfmt@latest && bunx oxfmt --migrate=prettier && bunx oxfmt

迁移前准备

Oxfmt 与 Prettier v3.8 版本的多数配置兼容。

主要差异包括：

• 默认 printWidth 为 100（Prettier 使用 80）
• 不支持 Prettier 插件（尽管一些流行的插件已原生实现）
• 部分选项不被支持（详见 配置参考）

详细信息请参见 不支持的功能。

第一步：将 Prettier 升级至 v3.8（可选）

Oxfmt 的输出最接近 Prettier v3.8。提前升级可最大程度减少格式差异。

第二步：安装 Oxfmt

npm

$ npm add -D oxfmt@latest

pnpm

$ pnpm add -D oxfmt@latest

yarn

$ yarn add -D oxfmt@latest

bun

$ bun add -D oxfmt@latest

deno

$ deno add -D npm:oxfmt@latest

第三步：迁移配置

Oxfmt 使用 .oxfmtrc.json 或 .oxfmtrc.jsonc 文件。基本示例：

.oxfmtrc.jsonc

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

运行 oxfmt --migrate prettier 可自动转换你的 Prettier 配置。

prettierrc.js 示例

迁移前：

prettierrc.js

module.exports = {
  singleQuote: true,
  jsxSingleQuote: true,
};

迁移后（.oxfmtrc.jsonc）：

.oxfmtrc.jsonc

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

prettierrc.yaml 示例

迁移前：

prettierrc.yaml

trailingComma: "es5"
tabWidth: 4
semi: false
singleQuote: true

迁移后（.oxfmtrc.jsonc）：

.oxfmtrc.jsonc

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "trailingComma": "es5",
  "tabWidth": 4,
  "semi": false,
  "singleQuote": true,
  "printWidth": 80,
}

第四步：更新脚本

package.json 脚本

{
  "scripts": {
-   "format": "prettier --write .",
+   "format": "oxfmt",
-   "format:check": "prettier --check ."
+   "format:check": "oxfmt --check"
  }
}

CI 工作流

  - name: 检查格式化
-   run: yarn prettier --check .
+   run: yarn oxfmt --check

Git 钩子（husky、lint-staged）

在 package.json 中：

"lint-staged": {
- "*": "prettier --write --no-error-on-unmatched-pattern"
+ "*": "oxfmt --no-error-on-unmatched-pattern"
}

第五步：运行格式化工具

npm run format

如果不再需要，可卸载 Prettier。

可选步骤

更新编辑器集成

参见 设置编辑器。

更新文档

如有必要，请在 CONTRIBUTING.md、AGENTS.md 和 CLAUDE.md 中更新对 Prettier 的引用。

更新 lint 规则

如存在，请移除 eslint-plugin-prettier。如需保留格式检查功能，可在 CI 流水线中用 oxfmt --check 替代。

注意：如果你计划继续使用 ESLint，应 保留或添加 eslint-config-prettier，以禁用可能与 Oxfmt 冲突的样式相关规则。eslint-config-prettier 与 eslint-plugin-prettier 不同，它不引入新的 lint 规则，仅作为配置文件使用。

此外，建议考虑迁移到 Oxlint。

更新 .git-blame-ignore-revs

将重新格式化的提交 SHA 添加到 .git-blame-ignore-revs，以使其在 git blame 中隐藏。

将 .prettierignore 替换为 "ignorePatterns"

若不再使用 Prettier，可选择将 .prettierignore 中的内容移至 Oxfmt 配置中的 "ignorePatterns"。更多信息请参见 忽略文件。