migrate-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:

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.

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:

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

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:

Prettier (top-level)

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

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

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

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