migrate-oxfmt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

This skill guides you through migrating a JavaScript/TypeScript project from Prettier or Biome to Oxfmt.

本技能将指导你完成将JavaScript/TypeScript项目从Prettier或Biome迁移至Oxfmt的流程。

Overview

概述

Oxfmt is a high-performance, Prettier-compatible code formatter. Most Prettier options are supported directly.

An automated migration tool is built into oxfmt, supporting both Prettier and Biome as migration sources.

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

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

Step 1: Run Automated Migration

步骤1：运行自动化迁移

From Prettier

从Prettier迁移

bash

npx oxfmt@latest --migrate prettier

This will:

Find and read your Prettier config (any format Prettier supports)
Create
```
.oxfmtrc.json
```
with migrated options
Migrate
```
.prettierignore
```
patterns to
```
ignorePatterns
```

Migrate

prettier-plugin-tailwindcss

options to

sortTailwindcss

Detect

prettier-plugin-packagejson

and enable

sortPackageJson

bash

npx oxfmt@latest --migrate prettier

此命令将：

查找并读取你的Prettier配置（支持Prettier的任何格式）
创建包含迁移后选项的
```
.oxfmtrc.json
```
文件
将
```
.prettierignore
```
中的规则迁移至
```
ignorePatterns
```

将

prettier-plugin-tailwindcss

的选项迁移至

sortTailwindcss

检测

prettier-plugin-packagejson

并启用

sortPackageJson

From Biome

从Biome迁移

bash

npx oxfmt@latest --migrate biome

This will:

Find and read
```
biome.json
```
or
```
biome.jsonc
```
Create
```
.oxfmtrc.json
```
with migrated options
Migrate negated patterns from
```
files.includes
```
to
```
ignorePatterns
```
Map Biome's two-level config (
```
formatter.*
```
and
```
javascript.formatter.*
```
) to oxfmt options

Biome option mapping:

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` )

Notes (both sources):

Fails if
```
.oxfmtrc.json
```
already exists. Delete it first if you want to re-run.
If no source config is found, creates a blank
```
.oxfmtrc.json
```
instead.
```
overrides
```
cannot be auto-migrated for either source and must be converted manually.

bash

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"` )
`formatter.bracketSameLine`	`bracketSameLine`
`formatter.bracketSpacing`	`bracketSpacing`
`formatter.attributePosition` ( `"multiline"` )	`singleAttributePerLine` ( `true` )

注意事项（两种迁移来源通用）：

如果
```
.oxfmtrc.json
```
已存在，迁移会失败。若需重新运行，请先删除该文件。
如果未找到来源配置，将创建一个空白的
```
.oxfmtrc.json
```
文件。
```
overrides
```
无法从任何来源自动迁移，必须手动转换。

Step 2: Review Generated Config

步骤2：检查生成的配置

After migration, review the generated

.oxfmtrc.json

for these key differences:

迁移完成后，检查生成的

.oxfmtrc.json

，注意以下关键差异：

printWidth

Prettier and Biome default is 80, oxfmt default is 100. The migration tool sets

printWidth: 80

if not specified in your source config. Decide whether to keep 80 or adopt 100.

Prettier和Biome的默认值为80，oxfmt的默认值为100。如果来源配置中未指定该选项，迁移工具会设置

printWidth: 80

。请决定是保留80还是改用100。

Unsupported Options (Prettier only)

不支持的选项（仅Prettier）

These Prettier options are skipped during migration:

Option	Status
`endOfLine: "auto"`	Not supported. Use `"lf"` or `"crlf"` explicitly
`experimentalTernaries`	Not supported in JS/TS files yet
`experimentalOperatorPosition`	Not supported in JS/TS files yet

以下Prettier选项在迁移时会被跳过：

选项	状态
`endOfLine: "auto"`	不支持。请显式使用 `"lf"` 或 `"crlf"`
`experimentalTernaries`	暂不支持在JS/TS文件中使用
`experimentalOperatorPosition`	暂不支持在JS/TS文件中使用

sortPackageJson (Prettier only)

sortPackageJson（仅Prettier）

Enabled by default in oxfmt, but the migration tool disables it unless

prettier-plugin-packagejson

was detected. Review whether you want this enabled.

Note: Oxfmt's sorting algorithm differs from

prettier-plugin-packagejson

oxfmt默认启用该选项，但迁移工具仅在检测到

prettier-plugin-packagejson

时才会启用它。请检查是否需要启用该选项。

注意：Oxfmt的排序算法与

prettier-plugin-packagejson

不同。

embeddedLanguageFormatting (Prettier only)

embeddedLanguageFormatting（仅Prettier）

Embedded language formatting (e.g., CSS-in-JS) generally works, but some formatting may differ from Prettier.

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

overrides

The

overrides

field cannot be auto-migrated from either Prettier or Biome. Convert manually:

json

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

overrides

字段无法从Prettier或Biome自动迁移，需手动转换：

json

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

Nested Config

嵌套配置

Oxfmt does not support nested configuration files (e.g., a separate

.oxfmtrc.json

in a subdirectory). If your project used per-directory Prettier or Biome configs, consolidate them using

overrides

with file glob patterns, or run oxfmt separately per directory with different working directories.

Oxfmt不支持嵌套配置文件（例如子目录中的独立

.oxfmtrc.json

）。如果你的项目使用了按目录划分的Prettier或Biome配置，请使用带有文件通配符的

overrides

合并它们，或者在不同目录中分别运行oxfmt并指定不同的工作目录。

Prettier-Compatible Options

兼容Prettier的选项

These options transfer directly with the same behavior:

tabWidth

useTabs

semi

singleQuote

jsxSingleQuote

quoteProps

trailingComma

arrowParens

bracketSpacing

bracketSameLine

endOfLine

proseWrap

htmlWhitespaceSensitivity

singleAttributePerLine

vueIndentScriptAndStyle

以下选项可直接迁移，且行为一致：

tabWidth

useTabs

semi

singleQuote

jsxSingleQuote

quoteProps

trailingComma

arrowParens

bracketSpacing

bracketSameLine

endOfLine

proseWrap

htmlWhitespaceSensitivity

singleAttributePerLine

vueIndentScriptAndStyle

Step 3: Configure Oxfmt Extensions

步骤3：配置Oxfmt扩展功能

Oxfmt offers features not available in Prettier:

Oxfmt提供了Prettier没有的功能：

sortImports

Sort import statements, inspired by

eslint-plugin-perfectionist/sort-imports

(disabled by default):

json

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

对导入语句进行排序，灵感来自

eslint-plugin-perfectionist/sort-imports

（默认禁用）：

json

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

sortTailwindcss

Replaces

prettier-plugin-tailwindcss

. Auto-migrated with renamed options:

Prettier (top-level)	oxfmt ( `sortTailwindcss.*` )
`tailwindConfig`	`config`
`tailwindStylesheet`	`stylesheet`
`tailwindFunctions`	`functions`
`tailwindAttributes`	`attributes`
`tailwindPreserveWhitespace`	`preserveWhitespace`
`tailwindPreserveDuplicates`	`preserveDuplicates`

替代

prettier-plugin-tailwindcss

。迁移时会自动重命名选项：

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

Other Extensions

其他扩展功能

Option	Default	Description
`insertFinalNewline`	`true`	Whether to add a final newline at end of file
`sortPackageJson`	`true`	Sort `package.json` keys. Set `{ "sortScripts": true }` to also sort scripts

选项	默认值	描述
`insertFinalNewline`	`true`	是否在文件末尾添加最终换行符
`sortPackageJson`	`true`	对 `package.json` 的键进行排序。设置 `{ "sortScripts": true }` 可同时排序脚本

Step 4: Update CI and Scripts

步骤4：更新CI和脚本

Replace formatter commands with oxfmt:

bash

undefined

将格式化工具命令替换为oxfmt：

bash

undefined

Before (Prettier)

之前（Prettier）

npx prettier --write . npx prettier --check .

Before (Biome)

之前（Biome）

npx biome format --write . npx biome check .

After

之后

npx oxfmt@latest npx oxfmt@latest --check

undefined

npx oxfmt@latest npx oxfmt@latest --check

undefined

Common CLI Options

常见CLI选项

Prettier / Biome	oxfmt
`prettier --write .` / `biome format --write .`	`oxfmt` (default: cwd, `--write` mode)
`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`

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`

File Type Coverage

文件类型支持

JS/TS: Formatted natively by oxfmt
TOML: Formatted natively (via taplo)
CSS, HTML, YAML, Markdown, GraphQL, etc.: Delegated to Prettier internally (when using
```
npx oxfmt
```
)

JS/TS：由oxfmt原生格式化
TOML：由oxfmt原生格式化（通过taplo）
CSS、HTML、YAML、Markdown、GraphQL等：内部委托给Prettier处理（使用
```
npx oxfmt
```
时）

Tips

小贴士

EditorConfig: Oxfmt reads

.editorconfig

automatically for

useTabs

tabWidth

endOfLine

insertFinalNewline

, and

printWidth

. Options in

.oxfmtrc.json

take precedence.

CI: Use
```
npx oxfmt@latest --check
```
to enforce formatting in CI.
LSP: Run
```
oxfmt --lsp
```
for editor integration via Language Server Protocol.

Schema support: Add

"$schema": "./node_modules/oxfmt/configuration_schema.json"

.oxfmtrc.json

for editor autocompletion.

Init: Run
```
npx oxfmt@latest --init
```
to create a default
```
.oxfmtrc.json
```
without migration.

EditorConfig：Oxfmt会自动读取
```
.editorconfig
```
中的
```
useTabs
```
、
```
tabWidth
```
、
```
endOfLine
```
、
```
insertFinalNewline
```
和
```
printWidth
```
选项。
```
.oxfmtrc.json
```
中的选项优先级更高。
CI：使用
```
npx oxfmt@latest --check
```
在CI中强制执行格式化规范。
LSP：运行
```
oxfmt --lsp
```
通过语言服务器协议实现编辑器集成。

架构支持：在

.oxfmtrc.json

中添加

"$schema": "./node_modules/oxfmt/configuration_schema.json"

可获得编辑器自动补全功能。

初始化：运行
```
npx oxfmt@latest --init
```
可创建默认的
```
.oxfmtrc.json
```
文件，无需迁移。

migrate-oxfmt

Original

Translation

Overview

概述

Step 1: Run Automated Migration

步骤1：运行自动化迁移

From Prettier

从Prettier迁移

From Biome

从Biome迁移

Step 2: Review Generated Config

步骤2：检查生成的配置

printWidth

printWidth

Unsupported Options (Prettier only)

不支持的选项（仅Prettier）

sortPackageJson (Prettier only)

sortPackageJson（仅Prettier）

embeddedLanguageFormatting (Prettier only)

embeddedLanguageFormatting（仅Prettier）

overrides

overrides

Nested Config

嵌套配置

Prettier-Compatible Options

兼容Prettier的选项

Step 3: Configure Oxfmt Extensions

步骤3：配置Oxfmt扩展功能

sortImports

sortImports

sortTailwindcss

sortTailwindcss

Other Extensions

其他扩展功能

Step 4: Update CI and Scripts

步骤4：更新CI和脚本

Before (Prettier)

之前（Prettier）

Before (Biome)

之前（Biome）

After

之后

Common CLI Options

常见CLI选项

File Type Coverage

文件类型支持

Tips

小贴士

References

参考资料