migrate-oxfmt

本技能指导您将 JavaScript/TypeScript 项目从 Prettier 或 Biome 迁移到 Oxfmt。

概述

Oxfmt 是一个高性能、与 Prettier 兼容的代码格式化工具。大多数 Prettier 选项都直接支持。

Oxfmt 内置了自动化迁移工具，支持 Prettier 和 Biome 作为迁移源。

步骤 1：运行自动化迁移

首先，判断自动化工具是否适用：

• 静态根配置（JSON/YAML，或仅导出普通对象的 JS/TS 配置）：使用下面的 --migrate。
• 动态 JS/TS 配置（包含环境分支或计算值等逻辑）：--migrate 仅写入已解析值的快照——逻辑不会保留。请手动迁移，将逻辑移植到 oxfmt.config.ts，并使用本指南中的选项映射。
• 嵌套的按目录配置：--migrate 仅处理当前目录中找到的配置。请手动迁移嵌套配置（参见步骤 2 中的“嵌套配置”）。

从 Prettier 迁移

npx oxfmt@latest --migrate prettier

这将：

• 查找并读取您的 Prettier 配置（支持 Prettier 支持的任何格式）
• 创建包含迁移后选项的 .oxfmtrc.json
• 将 .prettierignore 模式迁移到 ignorePatterns
• 将 prettier-plugin-tailwindcss 选项迁移到 sortTailwindcss
• 将 prettier-plugin-svelte 选项迁移到 svelte（svelteSortOrder → sortOrder，svelteAllowShorthand → allowShorthand，svelteIndentScriptAndStyle → indentScriptAndStyle）
• 检测 prettier-plugin-packagejson 并启用 sortPackageJson

从 Biome 迁移

npx oxfmt@latest --migrate biome

这将：

• 查找并读取 biome.json 或 biome.jsonc
• 创建包含迁移后选项的 .oxfmtrc.json
• 将 files.includes 中的否定模式迁移到 ignorePatterns
• 将 Biome 的两级配置（formatter.* 和 javascript.formatter.*）映射到 oxfmt 选项

Biome 选项映射：

Biome	oxfmt
formatter.indentStyle（"tab"/"space"）	useTabs（true/false）
formatter.indentWidth	tabWidth
formatter.lineWidth	printWidth
javascript.formatter.quoteStyle	singleQuote
javascript.formatter.jsxQuoteStyle	jsxSingleQuote
javascript.formatter.quoteProperties（"asNeeded"）	quoteProps（"as-needed"）
javascript.formatter.trailingCommas	trailingComma
javascript.formatter.semicolons（"always"/"asNeeded"）	semi（true/false）
javascript.formatter.arrowParentheses（"asNeeded"）	arrowParens（"avoid"）
javascript.formatter.bracketSameLine	bracketSameLine
formatter.bracketSpacing	bracketSpacing
formatter.attributePosition（"multiline"）	singleAttributePerLine（true）

注意（Biome）：

• 对于表中的 formatter.* 选项，同名的 javascript.formatter.* 值优先（如果存在）。bracketSameLine 仅从 javascript.formatter.bracketSameLine 读取。
• 未在 biome.json 中设置的选项会显式写入 Biome 的默认值到 .oxfmtrc.json（例如 printWidth: 80，useTabs: true），以便输出保留 Biome 的格式化行为。

注意（两个源）：

• 如果 .oxfmtrc.json 或 .oxfmtrc.jsonc 已存在，则失败。如果要重新运行，请先删除它。
• 如果未找到源配置，则创建一个空的 .oxfmtrc.json。
• 对于任一源，overrides 无法自动迁移，必须手动转换（如果检测到，会打印警告）。

步骤 2：审查生成的配置

迁移后，审查生成的 .oxfmtrc.json，注意以下关键差异：

printWidth

Prettier 和 Biome 的默认值是 80，oxfmt 的默认值是 100。如果源配置中未指定，迁移工具会设置 printWidth: 80。决定是保留 80 还是采用 100。

不支持的选项（仅 Prettier）

迁移过程中会跳过以下 Prettier 选项：

选项	状态
endOfLine: "auto"	不支持。请显式使用 "lf" 或 "crlf"
experimentalTernaries	尚不支持 JS/TS 文件
experimentalOperatorPosition	尚不支持 JS/TS 文件
requirePragma、insertPragma	不支持
parser、filepath	不适用于 oxfmt

tailwindFunctions / tailwindAttributes 中的正则值（例如 "/^my-/"）也会被跳过并发出警告——oxfmt 仅支持那里的字面字符串。

sortPackageJson（仅 Prettier）

Oxfmt 默认启用，但迁移工具会禁用它，除非检测到 prettier-plugin-packagejson。请审查是否需要启用此选项。

注意：Oxfmt 的排序算法与 prettier-plugin-packagejson 不同。

embeddedLanguageFormatting（仅 Prettier）

嵌入式语言格式化（例如 CSS-in-JS）通常可以工作，但某些格式化可能与 Prettier 不同。

overrides

overrides 字段无法从 Prettier 或 Biome 自动迁移。请手动转换：

{
  "overrides": [
    {
      "files": ["*.md"],
      "excludeFiles": ["CHANGELOG.md"],
      "options": { "tabWidth": 4 }
    }
  ]
}

（excludeFiles 是可选的。）

嵌套配置

Oxfmt 支持嵌套配置文件：子目录中的 .oxfmtrc.json 适用于该目录下的文件。传递 --disable-nested-config 以选择退出，仅使用根配置。

但是，--migrate 仅迁移当前目录中找到的配置——它不会遍历子目录。如果项目有按目录的 Prettier 或 Biome 配置，您必须自行迁移每个配置：手动将每个嵌套配置转换为同一目录中的 .oxfmtrc.json（使用本指南中的选项映射）。

与 Prettier 兼容的选项

这些选项直接转移，行为相同：
printWidth、tabWidth、useTabs、semi、singleQuote、jsxSingleQuote、quoteProps、trailingComma、arrowParens、bracketSpacing、bracketSameLine、objectWrap、endOfLine、proseWrap、htmlWhitespaceSensitivity、singleAttributePerLine、vueIndentScriptAndStyle、embeddedLanguageFormatting

步骤 3：配置 Oxfmt 扩展

Oxfmt 提供了 Prettier 中没有的功能：

sortImports

排序导入语句，灵感来自 eslint-plugin-perfectionist/sort-imports（默认禁用）：

{
  "sortImports": {
    "partitionByNewline": true,
    "newlinesBetween": false
  }
}

其他选项：partitionByComment、sortSideEffects、order、ignoreCase、internalPattern、groups、customGroups。

sortTailwindcss

替代 prettier-plugin-tailwindcss。自动迁移并重命名选项：

Prettier（顶层）	oxfmt（sortTailwindcss.*）
tailwindConfig	config
tailwindStylesheet	stylesheet
tailwindFunctions	functions
tailwindAttributes	attributes
tailwindPreserveWhitespace	preserveWhitespace
tailwindPreserveDuplicates	preserveDuplicates

其他扩展

选项	默认值	描述
insertFinalNewline	true	是否在文件末尾添加最终换行符
sortPackageJson	true	排序 package.json 键。设置 { "sortScripts": true } 以同时排序脚本
jsdoc	禁用	格式化 JSDoc 注释。设置为 true 或选项对象以进行精细控制
svelte	禁用	Svelte 格式化选项，替代 prettier-plugin-svelte（自动迁移）

步骤 4：更新 CI 和脚本

将格式化命令替换为 oxfmt：

# 之前（Prettier）
npx prettier --write .
npx prettier --check .

# 之前（Biome）
npx biome format --write .
npx biome check .

# 之后
npx oxfmt@latest
npx oxfmt@latest --check

常用 CLI 选项

Prettier / Biome	oxfmt
prettier --write . / biome format --write .	oxfmt（默认：当前工作目录，--write 模式）
prettier --check . / biome check .	oxfmt --check
prettier --list-different .	oxfmt --list-different
prettier --config path	oxfmt --config path
prettier --ignore-path .prettierignore	oxfmt --ignore-path .prettierignore
cat file | prettier --stdin-filepath=file.ts	cat file | oxfmt --stdin-filepath=file.ts

文件类型覆盖

• JS/TS、JSON/JSONC/JSON5、CSS/SCSS/Less、GraphQL：由 oxfmt 原生格式化
• TOML：原生格式化（通过 taplo）
• HTML、YAML、Markdown、Vue、Svelte 等：内部委托给 Prettier（使用 npx oxfmt 时）

提示

• 配置文件：除了 .oxfmtrc.json 之外，还支持 .oxfmtrc.jsonc 和 oxfmt.config.ts 作为自动发现的配置文件名称。--migrate 和 --init 仅生成 .oxfmtrc.json；除非用户明确要求其他格式或源配置包含要保留的逻辑（参见步骤 1），否则保持原样。
• EditorConfig：Oxfmt 自动读取 .editorconfig 以获取 useTabs、tabWidth、endOfLine、insertFinalNewline、printWidth 和 singleQuote。.oxfmtrc.json 中的选项优先。
• CI：使用 npx oxfmt@latest --check 在 CI 中强制执行格式化。
• LSP：运行 oxfmt --lsp 以通过语言服务器协议进行编辑器集成。
• Schema 支持：将 "$schema": "./node_modules/oxfmt/configuration_schema.json" 添加到 .oxfmtrc.json 以启用编辑器自动补全。
• 初始化：运行 npx oxfmt@latest --init 以创建默认的 .oxfmtrc.json，无需迁移。

参考

• CLI 参考
• 配置文件参考
• 不支持的功能