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

排序 import 陳述式，靈感來自 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 } 也可排序 scripts
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 支援：在 .oxfmtrc.json 中加入 "$schema": "./node_modules/oxfmt/configuration_schema.json" 以啟用編輯器自動完成。
• 初始化：執行 npx oxfmt@latest --init 以建立預設的 .oxfmtrc.json，無需遷移。

參考資料

• CLI 參考
• 設定檔參考
• 不支援的功能