Migrating from Prettier to oxfmt

This guide is intended to help migrate projects from Prettier to oxfmt.

Note that oxfmt is in alpha, and may not be suitable for production use in complex setups.

The oxfmt alpha only supports formatting JavaScript and TypeScript files (including JSX syntax). If you need support for other languages like JSON, YAML, or Markdown, you may want to wait.

Step 1: Upgrade Prettier to v3.7

This step is optional, but will make it easier to determine which differences between oxfmt and prettier are "real".

To minimize the number of changes when migrating to oxfmt, you may want to upgrade Prettier to version 3.7 first, as it is the latest release of Prettier (from Nov 2025) and will be most similar to the output of oxfmt.

Step 2: Install oxfmt

Install oxfmt as a development dependency with your package manager of choice:

::: code-group

$ npm add -D oxfmt@latest

$ pnpm add -D oxfmt@latest

$ yarn add -D oxfmt@latest

$ bun add -D oxfmt@latest

$ deno add -D npm:oxfmt@latest

:::

Step 2.5: Caveats for migrating your config file

Before migrating your Prettier configuration file, please be aware of the following caveats:

• oxfmt's formatting output is closest to Prettier v3.7. If you are using an older version of Prettier, you will see more differences in formatting output.
• oxfmt aims to be mostly compatible with Prettier out-of-the-box, but there may still be some differences in formatting output.
• Note that oxfmt uses a printWidth of 100 characters by default, unlike Prettier's 80. If your Prettier configuration does not set printWidth explicitly, you should make sure to set "printWidth": 80 in your oxfmt config file to minimize differences.
• Prettier plugins are not yet supported.
• Some Prettier options are not supported. See the oxfmt documentation for the full list of supported options.

Step 3: Migrate Prettier configuration file

.oxfmtrc.jsonc is the configuration file for oxfmt. Only JSON files are supported.

A basic .oxfmtrc.jsonc file looks like this:

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "singleQuote": false,
  "printWidth": 100
}

If you have a basic .prettierrc file, you can simply rename the file with mv .prettierrc .oxfmtrc.jsonc.

If you are using YAML or JavaScript to configure Prettier, you will need to convert the configuration to JSON format manually, although for simple configs this should be trivial.

prettierrc.js

Here's an example of migrating a prettierrc.js file.

Before:

module.exports = {
  singleQuote: true,
  jsxSingleQuote: true
};

After (.oxfmtrc.jsonc):

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "singleQuote": true,
  "jsxSingleQuote": true,
  "printWidth": 80
}

prettierrc.yaml

Here's an example of migrating a prettierrc.yaml file.

Before:

trailingComma: "es5"
tabWidth: 4
semi: false
singleQuote: true

After (.oxfmtrc.jsonc):

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "trailingComma": "es5",
  "tabWidth": 4,
  "semi": false,
  "singleQuote": true,
  "printWidth": 80
}

Step 4: Update Formatting Scripts

Update any formatting scripts you currently have, for example in package.json, shell scripts, or pre-commit scripts.

package.json scripts

Before:

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

After:

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

CI Workflows

Update any CI workflows that run Prettier, particularly prettier --check.

Before:

- name: Check formatting
  run: yarn prettier --check .

After:

- name: Check formatting
  run: yarn oxfmt --check

Git Hooks (e.g. husky, lint-staged)

Before:

"lint-staged": {
  "*": "prettier --write"
}

After:

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

Step 5: Run formatter

Run oxfmt on your codebase to check for any changes and ensure that the configuration was migrated correctly:

yarn oxfmt (or npm run oxfmt, etc.)

Step 6: Uninstall Prettier (optional)

If you no longer need Prettier, you can uninstall it:

yarn remove prettier, etc.

Step 7: Done!

You have now migrated to oxfmt :)

Please see the "miscellaneous migration steps" section below for any additional steps you may need to take.

Miscellaneous migration steps

These are only applicable for some setups, so skip them if they don't apply to you.

Update editor integrations

Note that the oxc VS Code extension includes oxfmt support, but it is experimental and incomplete. It may not fully work yet, so please be mindful of this before migrating.

If you have any editor integrations for Prettier, update them to use oxfmt instead. For example, update .vscode/settings.json to use oxfmt:

Before:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

After:

{
  "editor.defaultFormatter": "oxc.oxc-vscode"
}

And update .vscode/extensions.json to recommend the oxc extension instead of Prettier.

Before:

{
  "recommendations": [
    "esbenp.prettier-vscode"
  ]
}

After:

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

Update CONTRIBUTING.md

If you have a CONTRIBUTING.md file that references Prettier, update those references to use oxfmt.

Update AGENTS.md/CLAUDE.md

If you use an AGENTS.md or CLAUDE.md file, you should check for references to Prettier. If you have any references in those files, you'll want to update them to reference oxfmt and oxfmt's CLI commands instead.

Update lint rules

If you have any lint rules that check for Prettier formatting (e.g. eslint-plugin-prettier), you should remove them.

While you're at it, you could also consider migrating to oxlint ;)

Create/update .git-blame-ignore-revs

If you want to avoid extra noise in your git blame, you can add the commit hash where you reformatted files using oxfmt to your .git-blame-ignore-revs file. This will make git blame ignore that commit when showing blame information. This file is supported natively by git, and by both GitHub and GitLab.