migrate-oxfmt（迁移 oxfmt）

This skill guides you through migrating a JavaScript/TypeScript project from Prettier or Biome to 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.

Step 1: Run Automated Migration

From Prettier

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

From Biome

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:

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.

Step 2: Review Generated Config

After migration, review the generated .oxfmtrc.json for these key differences:

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.

Unsupported Options (Prettier only)

These Prettier options are skipped during migration:

sortPackageJson (Prettier only)

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.

embeddedLanguageFormatting (Prettier only)

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

overrides

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

{
  "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.

Prettier-Compatible Options

These options transfer directly with the same behavior: tabWidth, useTabs, semi, singleQuote, jsxSingleQuote, quoteProps, trailingComma, arrowParens, bracketSpacing, bracketSameLine, endOfLine, proseWrap, htmlWhitespaceSensitivity, singleAttributePerLine, vueIndentScriptAndStyle

Step 3: Configure Oxfmt Extensions

Oxfmt offers features not available in Prettier:

sortImports

Sort import statements, inspired by eslint-plugin-perfectionist/sort-imports (disabled by default):

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

sortTailwindcss

Replaces prettier-plugin-tailwindcss. Auto-migrated with renamed options:

Other Extensions

Step 4: Update CI and Scripts

Replace formatter commands with 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

Common CLI Options

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)

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" to .oxfmtrc.json for editor autocompletion.
• Init: Run npx oxfmt@latest --init to create a default .oxfmtrc.json without migration.

References

• CLI Reference
• Config File Reference
• Unsupported Features