Prettier to Oxfmt: The Complete Migration Guide

Moving from Prettier to Oxfmt is not hard, but doing it cleanly in a real codebase takes more than swapping one command in package.json.

Oxfmt is designed to fit into existing Prettier-style workflows. It supports the usual JavaScript and TypeScript stack, and the current docs also list support for JSON, YAML, TOML, HTML, CSS, Markdown, MDX, GraphQL, Vue, Angular, Handlebars, and more. The migration path is good enough that most teams can get from Prettier to Oxfmt in one pass, as long as they review the details that automation cannot decide for them.

This guide covers the full migration path: what to audit first, how to run the automatic migration, what to manually review, how to replace common Prettier plugin setups, how to update CI and editors, and how to land the formatting diff without making your repository painful to work in.

Why teams consider Oxfmt

The migration usually starts for one of three reasons:

• faster formatting in large repositories and CI
• fewer moving parts around Prettier plugins
• a formatter that behaves like Prettier without needing a full re-think of team workflow

That does not mean every repository should migrate immediately. If your setup depends heavily on niche Prettier plugins, nested formatter configs, or framework-specific formatting that still relies on plugin support, you should verify support before touching the repo.

The official compatibility matrix is especially worth checking if your project formats Svelte, Astro, or SvelteKit files, because those currently depend on Prettier plugin support that the matrix marks as not yet available. Angular and Analog also have caveats around .html support versus .component.html. If your codebase is mostly JS, TS, JSX, TSX, JSON, CSS, Markdown, and MDX, the migration is usually much more direct.

Before you touch the formatter

A clean migration starts with a short audit of your current Prettier setup. You want to know exactly what you are replacing before you ask an automated tool to convert it.

Check these items first:

• where your Prettier config lives: .prettierrc, prettier.config.js, YAML, JSON, or the prettier field in package.json
• whether you rely on overrides
• whether you have nested config files in subdirectories
• whether .editorconfig is part of your formatting behavior
• whether .prettierignore contains important repository-specific ignores
• which Prettier plugins are installed and whether they are functionally required
• whether git hooks, lint-staged, editor settings, and CI still call Prettier directly

If you are on an older Prettier version, it is worth upgrading to Prettier v3.8 before migrating. Oxfmt documents that its output is closest to Prettier v3.8, so upgrading first reduces surprise diffs.

Step 1: Install Oxfmt without breaking rollback

Install Oxfmt as a dev dependency first. Keep Prettier in the repo until the migration is fully verified.

# npm
npm add -D oxfmt@latest

# pnpm
pnpm add -D oxfmt@latest

# yarn
yarn add -D oxfmt@latest

# bun
bun add -D oxfmt@latest

At this point, do not remove Prettier yet. Keeping both tools temporarily makes rollback trivial if you discover a plugin dependency or unsupported config behavior after the first formatting run.

Step 2: Run the automatic migration

The official fast path from the Oxc docs is:

npx oxfmt --migrate=prettier

Or, if you prefer to install and migrate in one shot:

npm add -D oxfmt@latest && npx oxfmt --migrate=prettier && npx oxfmt

The migration command does useful work out of the box:

• it reads your existing Prettier config in supported formats
• it creates .oxfmtrc.json
• it migrates .prettierignore patterns into ignorePatterns
• it detects common plugin-based behavior such as Tailwind class sorting
• it detects prettier-plugin-packagejson and maps that behavior to Oxfmt

There are two immediate gotchas:

• if .oxfmtrc.json already exists, the migration command fails instead of overwriting it
• if your setup uses overrides, those are not auto-migrated and need manual conversion

If your project did not have a discoverable Prettier config, Oxfmt will still create a config file, but you will need to decide what belongs in it.

Step 3: Review the generated config carefully

This is where the migration becomes a real engineering task rather than a copy-paste command.

Oxfmt looks for configuration in:

• .oxfmtrc.json
• .oxfmtrc.jsonc
• oxfmt.config.ts

It searches from the current directory upward through the tree. You can also pass a config explicitly with -c.

A clean starter config often looks like this:

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "printWidth": 80,
  "singleQuote": true,
  "semi": true,
  "trailingComma": "all",
  "ignorePatterns": ["dist/**", "coverage/**"],
  "overrides": [
    {
      "files": ["*.md"],
      "options": {
        "tabWidth": 2
      }
    }
  ]
}

Decision 1: printWidth

This is the biggest formatting decision in most migrations.

Prettier defaults to 80. Oxfmt defaults to 100. The migration tool sets printWidth: 80 when your Prettier config did not define it, which is a sensible compatibility choice.

Do not casually change this during migration. If your goal is a low-risk swap, keep 80 for the first rollout. If your team actually wants 100, do that as a separate formatting decision so the migration diff and the style-policy diff do not get mixed together.

Decision 2: .editorconfig

Oxfmt reads .editorconfig, including:

• end_of_line to endOfLine
• indent_style to useTabs
• indent_size to tabWidth
• max_line_length to printWidth
• insert_final_newline to insertFinalNewline

That sounds familiar, but there is a detail teams miss: Oxfmt uses only the nearest .editorconfig from the current directory. Nested .editorconfig files are not merged, and root = true is not respected the same way some teams expect.

If your repository depends on layered .editorconfig behavior, validate that before rollout. Also remember the precedence model: defaults come first, then root Oxfmt config, then Oxfmt overrides, and only then does .editorconfig provide fallback values for fields you left unset.

Decision 3: overrides

Oxfmt supports overrides, but Prettier overrides are not auto-migrated. If your repo uses file-specific rules, convert them manually.

Example:

{
  "overrides": [
    {
      "files": ["*.test.ts", "*.spec.ts"],
      "options": {
        "printWidth": 120
      }
    },
    {
      "files": ["*.md", "*.html"],
      "excludeFiles": ["*.min.js"],
      "options": {
        "tabWidth": 4
      }
    }
  ]
}

This matters a lot in monorepos and documentation-heavy repos, where markdown, tests, generated files, and application code may not share the same ideal formatting rules.

Decision 4: nested config files

Oxfmt does not support nested formatter config files in subdirectories. If your Prettier setup relies on separate config files in multiple folders, you need to consolidate those rules into one config using overrides, or run Oxfmt separately in different working directories.

For teams used to per-package formatting configs, this is often the first real architectural change in the migration.

Decision 5: ignore behavior

Oxfmt supports several ignore mechanisms:

• ignorePatterns in .oxfmtrc.json
• .gitignore
• .prettierignore for compatibility

They do not behave exactly the same.

Files ignored by .gitignore can still be formatted if you explicitly pass them on the command line. Files ignored by ignorePatterns or .prettierignore cannot be formatted even if you specify them directly. Lock files are always ignored, and VCS directories plus node_modules are ignored by default.

That distinction matters for scripts, hooks, and one-off formatting commands.

Step 4: Replace plugin behavior with Oxfmt-native features

Oxfmt does not support arbitrary Prettier plugins directly. This is the point where teams either gain simplicity or hit a blocker.

The good news is that Oxfmt includes built-in replacements for some of the most common plugin-driven workflows.

If you use Tailwind, the configuration names change a bit under sortTailwindcss. If you sort imports today, decide whether you want Oxfmt to take that job or whether import ordering should remain in ESLint or another dedicated tool. Do not silently turn on import sorting during migration unless your current workflow already does it, because that creates a much larger diff than the formatter swap alone.

Oxfmt also includes embedded formatting support for cases like CSS-in-JS and GraphQL-in-template usage, but the official config reference notes that some embedded-language scenarios remain incomplete. That is not usually a blocker, but it is worth checking on representative files before you remove Prettier entirely.

Step 5: Update the commands people and machines actually run

Migration is not complete when .oxfmtrc.json exists. It is complete when developers, editors, hooks, and CI all run the new formatter consistently.

Start with package.json:

{
  "scripts": {
    "fmt": "oxfmt",
    "fmt:check": "oxfmt --check"
  }
}

If you are replacing old Prettier commands, the diff usually looks like this:

{
  "scripts": {
-   "format": "prettier --write .",
-   "format:check": "prettier --check ."
+   "fmt": "oxfmt",
+   "fmt:check": "oxfmt --check"
  }
}

The official docs also note that running oxfmt with no arguments formats the current directory, which makes it a close replacement for prettier --write ..

CI

Add a formatting check job and make it fail on differences:

name: CI

on:
  pull_request:
  push:
    branches: [main]

permissions: {}

jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: lts/*
      - run: npm ci
      - run: npm run fmt:check

If your team likes auto-fixing formatting on pull requests, the official CI guide also calls out autofix.ci as an option.

Git hooks and lint-staged

For staged-file formatting, Oxfmt recommends:

{
  "lint-staged": {
    "*": "oxfmt --no-error-on-unmatched-pattern"
  }
}

That --no-error-on-unmatched-pattern flag matters because staged files may include unsupported file types, and you do not want the hook failing for that reason alone.

Editors

The official editor guide says editor integrations use oxfmt --lsp from your project, so Oxfmt needs to be installed locally.

For VS Code and other VS Code-based editors, the recommended team setup is:

{
  "recommendations": ["oxc.oxc-vscode"]
}

And:

{
  "oxc.fmt.configPath": ".oxfmtrc.json",
  "editor.defaultFormatter": "oxc.oxc-vscode",
  "editor.formatOnSave": true
}

This is a small step, but it prevents the classic migration bug where CI is running Oxfmt while half the team is still formatting locally with Prettier on save.

Step 6: Run the migration like a production change

This is the part most teams under-plan.

A formatter migration changes a lot of lines quickly. That means the technical risk is less about runtime behavior and more about repository health, reviewer fatigue, and downstream workflow noise.

A production-safe rollout usually looks like this:

1. Create a dedicated migration branch or PR.
2. Migrate the config and review it before formatting the repository.
3. Update scripts, CI, hooks, and editor recommendations in the same PR.
4. Run Oxfmt once across the repo.
5. Skim representative files across app code, config, markdown, and generated-adjacent areas.
6. Add the formatting commit SHA to .git-blame-ignore-revs.
7. Merge the formatter migration independently from feature work.
8. Remove Prettier only after the new workflow is stable.

That sequence keeps the migration easy to reason about. It also makes rollback possible if you discover framework-specific or plugin-specific gaps after the first pass.

Step 7: Verify the migration before removing Prettier

A good verification pass includes more than a single --check run.

Use a short checklist:

• run oxfmt --check
• run your normal test and build pipeline
• search the repo for stale prettier references in scripts, docs, and workflows
• confirm editor recommendations point to Oxfmt
• confirm hooks use Oxfmt rather than Prettier
• confirm .oxfmtrc.json contains the settings your team actually wants
• confirm a few representative files still look the way your team expects

Two practical command examples:

npx oxfmt --check
rg -n "prettier" package.json .github .vscode .husky .lintstagedrc* .

If the second command still finds active Prettier usage, your migration is not done yet.

Common pitfalls

These are the issues most likely to surprise teams during rollout:

• assuming the prettier field in package.json is a long-term config home; Oxfmt expects its own config files
• forgetting that overrides need manual conversion
• changing printWidth during migration and then blaming Oxfmt for the larger diff
• leaving Prettier in hooks or editor settings, which creates format churn between local work and CI
• assuming nested formatter configs will keep working
• assuming nested .editorconfig files are merged
• enabling sortImports during migration without realizing it changes many files beyond formatting
• forgetting to update documentation like CONTRIBUTING.md, AGENTS.md, or team setup docs

A migration checklist you can actually use

If you want the shortest production checklist, use this:

1. Upgrade to Prettier v3.8 first if you are on an older version.
2. Audit plugins, overrides, ignores, and nested config usage.
3. Install oxfmt.
4. Run oxfmt --migrate=prettier.
5. Review .oxfmtrc.json for printWidth, overrides, ignore behavior, and plugin replacements.
6. Add fmt and fmt:check scripts.
7. Update CI, hooks, and editor settings.
8. Run Oxfmt across the repository.
9. Verify build, tests, and formatting checks.
10. Add the reformat commit to .git-blame-ignore-revs.
11. Remove Prettier when the new workflow is fully in place.

Final take

The best Oxfmt migrations are boring. They do not try to redesign style rules, editor conventions, hook behavior, and CI policy at the same time. They migrate one tool carefully, keep the repo stable, and leave behind a simpler formatting setup than the one they started with.

If you approach the change as infrastructure work instead of a cosmetic cleanup, Oxfmt is a very manageable migration.