从 Prettier 迁移

本指南介绍如何从 Prettier 迁移到 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

使用 Skills 迁移

您可以使用 migrate-oxfmt skill 交互式迁移：

npx skills add https://github.com/oxc-project/oxc --skill migrate-oxfmt

安装后，运行 /migrate-oxfmt，agent 将引导您完成整个迁移过程。

迁移前须知

Oxfmt 与 Prettier v3.8 在许多配置上兼容。

主要区别：

• 默认 printWidth 是 100（Prettier 使用 80）
• 不支持 Prettier 插件（但一些热门插件已原生实现）
• 部分选项不支持（参见 配置参考）

详见 不支持的功能，以及 兼容性矩阵 了解文件类型支持。

步骤 1：升级 Prettier 到 v3.8（可选）

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

步骤 2：安装 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

步骤 3：迁移配置

Oxfmt 使用 .oxfmtrc.json、.oxfmtrc.jsonc 或 oxfmt.config.ts。基本示例：

.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,
};

迁移后（oxfmt.config.ts）：

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  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,
}

步骤 4：更新脚本

package.json 脚本

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

CI 工作流

  - name: Check formatting
-   run: yarn prettier --check .
+   run: yarn oxfmt --check

Git hooks（husky、lint-staged）

在 package.json 中：

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

步骤 5：运行格式化

npm run format

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

可选步骤

更新编辑器集成

参见 编辑器设置。

更新文档

更新 CONTRIBUTING.md、AGENTS.md 和 CLAUDE.md 中对 Prettier 的引用（如适用）。

更新 lint 规则

如果存在 eslint-plugin-prettier，请移除。如需要，可以在 CI 流水线中用 oxfmt --check job 替代。

注意，如果您打算继续使用 ESLint，您_应该_保留或添加 eslint-config-prettier 来禁用可能与 Oxfmt 冲突的样式相关 ESLint 规则。eslint-config-prettier 与 eslint-plugin-prettier 不同，它没有新的 lint 规则，只是一个配置。

另外，考虑迁移到 Oxlint。

更新 .git-blame-ignore-revs

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

用 "ignorePatterns" 替换 .prettierignore

如果您不再使用 Prettier，可以选择将 .prettierignore 的内容移到 Oxfmt 配置的 "ignorePatterns" 中。注意 .prettierignore 全局生效，而 ignorePatterns 的作用域仅限于它所属的配置文件。在嵌套配置设置中，这可能会改变哪些文件被忽略。详见 忽略文件。