migrate-oxfmt

このスキルは、JavaScriptおよびTypeScriptプロジェクトをPrettierまたはBiomeから Oxfmt へ移行するプロセスをガイドします。

概要

Oxfmtは高性能でPretterと互換性のあるコードフォーマッターです。Prettierのオプションのほとんどが直接サポートされています。

oxfmtに内蔵された自動化された移行ツールは、PrettierとBiomeの両方をソースとしてサポートしています。

ステップ1: 自動化移行ツールを実行

Prettierからの移行

npx oxfmt@latest --migrate prettier

このコマンドは以下の処理を行います:

• Prettierの設定ファイルを検索して読み込む（Prettierがサポートするすべての形式）
• 移行されたオプション付きで .oxfmtrc.json を作成
• .prettierignore のパターンを ignorePatterns に移行
• prettier-plugin-tailwindcss のオプションを sortTailwindcss に移行
• prettier-plugin-packagejson を検出して sortPackageJson を有効化

Biomeからの移行

npx oxfmt@latest --migrate biome

このコマンドは以下の処理を行います:

• biome.json または biome.jsonc を検索して読み込む
• 移行されたオプション付きで .oxfmtrc.json を作成
• files.includes からの否定パターンを ignorePatterns に移行
• Biomeの2段階の設定（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")
formatter.bracketSameLine	bracketSameLine
formatter.bracketSpacing	bracketSpacing
formatter.attributePosition ("multiline")	singleAttributePerLine (true)

注釈（両方のソース共通）:

• .oxfmtrc.json が既に存在する場合は失敗します。再実行したい場合は最初に削除してください。
• ソース設定が見つからない場合は、代わりに空の .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ファイルではまだサポートされていません

sortPackageJson（Prettierのみ）

oxfmtではデフォルトで有効になっていますが、移行ツールは prettier-plugin-packagejson が検出されない限り無効にします。これを有効にするかどうかを確認してください。

注意: Oxfmtのソートアルゴリズムは prettier-plugin-packagejson と異なります。

embeddedLanguageFormatting（Prettierのみ）

埋め込み言語フォーマット（例：CSS-in-JS）は一般的に機能しますが、いくつかのフォーマットがPrettierと異なる場合があります。

overrides

overrides フィールドはPrettierまたはBiomeから自動移行できません。手動で変換してください:

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

ネストされた設定

Oxfmtはネストされた設定ファイル（例：サブディレクトリ内の別の .oxfmtrc.json）をサポートしていません。プロジェクトが1ディレクトリごとのPrettierまたはBiome設定を使用していた場合、ファイルグロブパターンを使用して overrides を使って統合するか、異なるワーキングディレクトリで1ディレクトリごとにoxfmtを実行してください。

Prettier互換のオプション

これらのオプションは同じ動作で直接転送されます: tabWidth, useTabs, semi, singleQuote, jsxSingleQuote, quoteProps, trailingComma, arrowParens, bracketSpacing, bracketSameLine, endOfLine, proseWrap, htmlWhitespaceSensitivity, singleAttributePerLine, vueIndentScriptAndStyle

ステップ3: Oxfmt拡張機能を設定

Oxfmtはprettierで利用できない機能を提供します:

sortImports

インポートステートメントをソート、eslint-plugin-perfectionist/sort-imports にインスピレーションを受けています（デフォルトは無効）:

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

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 } で スクリプトもソート

ステップ4: CIとスクリプトを更新

フォーマッターコマンドをoxfmtに置き換えます:

# Before (Prettier)
npx prettier --write .
npx prettier --check .

# Before (Biome)
npx biome format --write .
npx biome check .

# After
npx oxfmt@latest
npx oxfmt@latest --check

共通CLIオプション

Prettier / Biome	oxfmt
prettier --write . / biome format --write .	oxfmt（デフォルト: cwd, --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: oxfmtによってネイティブにフォーマット
• TOML: ネイティブにフォーマット（taploを経由）
• CSS、HTML、YAML、Markdown、GraphQL等: npx oxfmt 使用時にPrettierに内部的に委譲

ヒント

• EditorConfig: Oxfmtは useTabs、tabWidth、endOfLine、insertFinalNewline、printWidth について自動的に .editorconfig を読み込みます。.oxfmtrc.json のオプションが優先されます。
• CI: CI においてフォーマットを強制するには npx oxfmt@latest --check を使用してください。
• LSP: エディター統合にはLanguage Server Protocolを経由して oxfmt --lsp を実行してください。
• スキーマサポート: エディターのオートコンプリートのために .oxfmtrc.json に "$schema": "./node_modules/oxfmt/configuration_schema.json" を追加してください。
• Init: 移行なしでデフォルト .oxfmtrc.json を作成するには npx oxfmt@latest --init を実行してください。

参考資料

• CLI Reference
• Config File Reference
• Unsupported Features