从 Prettier 迁移

🌐 Migrate from Prettier

本指南涵盖从 Prettier 迁移到 Oxfmt 的内容。

🌐 This guide covers migrating from Prettier to Oxfmt.

WARNING

Oxfmt 处于 α 版本，可能不适合复杂的设置。

快速开始

🌐 Quick start

对于简单的设置，只需使用一条命令进行迁移：

🌐 For simple setups, migrate with a single command:

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

在迁移之前

🌐 Before you migrate

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

🌐 Oxfmt is compatible with Prettier v3.8 for many configurations.

主要区别：

🌐 Key differences:

• 默认 printWidth 是 100（Prettier 使用 80）
• 不支持 Prettier 的插件（尽管一些流行的插件是原生实现的）
• 某些选项不受支持（参见配置参考）

有关详细信息，请参阅 不受支持的功能。

🌐 See Unsupported features for details.

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

🌐 Step 1: Upgrade Prettier to v3.8 (optional)

Oxfmt 的输出最接近 Prettier v3.8。先升级可以最小化格式差异。

🌐 Oxfmt's output is closest to Prettier v3.8. Upgrading first minimizes formatting differences.

步骤 2：安装 Oxfmt

🌐 Step 2: Install 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：迁移配置

🌐 Step 3: Migrate configuration

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

🌐 Oxfmt uses .oxfmtrc.json or .oxfmtrc.jsonc. Basic example:

.oxfmtrc.jsonc

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

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

🌐 Run oxfmt --migrate prettier to convert your Prettier config automatically.

prettierrc.js 示例

🌐 prettierrc.js example

之前：

🌐 Before:

prettierrc.js

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

在（.oxfmtrc.jsonc）之后：

🌐 After (.oxfmtrc.jsonc):

.oxfmtrc.jsonc

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

prettierrc.yaml 示例

🌐 prettierrc.yaml example

之前：

🌐 Before:

prettierrc.yaml

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

在（.oxfmtrc.jsonc）之后：

🌐 After (.oxfmtrc.jsonc):

.oxfmtrc.jsonc

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

步骤 4：更新脚本

🌐 Step 4: Update scripts

package.json 脚本

🌐 package.json scripts

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

持续集成工作流

🌐 CI workflows

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

Git 钩子（husky, lint-staged）

🌐 Git hooks (husky, lint-staged)

在 package.json 中：

🌐 In package.json:

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

步骤 5：运行格式化工具

🌐 Step 5: Run formatter

npm run format

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

🌐 Uninstall Prettier if it is no longer needed.

可选步骤

🌐 Optional steps

更新编辑器集成

🌐 Update editor integrations

参见[设置编辑器]（./editors）。

🌐 See Setup editors.

更新文档

🌐 Update documentation

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

🌐 Update references to Prettier in CONTRIBUTING.md, AGENTS.md, and CLAUDE.md if applicable.

更新 lint 规则

🌐 Update lint rules

如果存在，请移除 eslint-plugin-prettier。如有需要，可以在你的 CI 流水线中用 oxfmt --check 任务替代它。

🌐 Remove eslint-plugin-prettier if present. If needed, it can be replaced by a oxfmt --check job in your CI pipelines.

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

🌐 Note that if you intend to continue using ESLint, you should keep or add eslint-config-prettier to disable styling-related ESLint rules that might conflict with Oxfmt. eslint-config-prettier is different from eslint-plugin-prettier, as it has no new lint rules. It is only a config.

另外，考虑迁移到 Oxlint。

🌐 Also, consider migrating to Oxlint.

更新 .git-blame-ignore-revs

🌐 Update .git-blame-ignore-revs

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

🌐 Add the reformatting commit SHA to .git-blame-ignore-revs to hide it from git blame.

将 .prettierignore 替换为 "ignorePatterns"

🌐 Replace .prettierignore with "ignorePatterns"

如果你不再使用 Prettier，你可以选择将其内容从 .prettierignore 移动到 Oxfmt 配置中的 "ignorePatterns"。有关更多信息，请参阅 忽略文件。

🌐 If you no longer use Prettier, you can optionally move its contents from .prettierignore to "ignorePatterns" in your Oxfmt config. See Ignore files for more information.