Migrate OxfmtSAFE

⚓ A collection of high-performance JavaScript tools.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: migrate-oxfmt
description: Guide for migrating a project from Prettier or Biome to Oxfmt. Use when asked to migrate, convert, or switch a project's formatter from Prettier or Biome to Oxfmt.
---

This skill guides you through migrating a project from Prettier or Biome to [Oxfmt](https://oxc.rs/docs/guide/usage/formatter).

## 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

First, decide whether the automated tool fits:

- Static config (JSON, or a JS/TS config that just exports a plain object): use `--migrate` below.
- Dynamic JS/TS config (logic such as environment branches or computed values): `--migrate` writes only a resolved snapshot of the values, and the logic does not survive (a warning is printed). Port the logic to `oxfmt.config.ts` manually with the option mappings in this guide.
- Nested per-directory configs: `--migrate` only handles the config in the current directory. Run it again in each nested directory (see "Nested Config" in Step 2).

### From Prettier

```bash
npx oxfmt@latest --migrate prettier
```

This will:

- Find your Prettier config in the current directory, in the same order as Prettier
  - Supported: `package.json` (`prettier` field), `.prettierrc` (JSON only), `.prettierrc.json`, and JS/TS configs (`.prettierrc.*`, `prettier.config.*`)
  - Shareable configs (e.g. `"prettier": "@company/prettier-config"`) are resolved
  - YAML, JSON5 and TOML configs are not supported. Convert them to JSON or JS first
- Create `.oxfmtrc.json` with migrated options
  - Only Prettier-compatible options are migrated, others are skipped with a warning
- Migrate `overrides`
  - `overrides[].options.parser` is migrated to `associations[].language`
- Migrate `.prettierignore` patterns to `ignorePatterns`
- Migrate `prettier-plugin-tailwindcss` options to `sortTailwindcss`
- Migrate `prettier-plugin-svelte` options to `svelte` (`svelteSortOrder` → `sortOrder`, `svelteAllowShorthand` → `allowShorthand`, `svelteIndentScriptAndStyle` → `indentScriptAndStyle`)
- Migrate `prettier-plugin-astro` options to `astro` (`astroAllowShorthand` → `allowShorthand`, `astroSkipFrontmatter` → `skipFrontmatter`, `astroCompressHTML` → `compressHTML`)
- Detect `prettier-plugin-packagejson` and enable `sortPackageJson`
- Skip other plugins with a warning

Notes (Prettier):

- Fails if no Prettier config is found in the current directory. Use `--init` to create a blank `.oxfmtrc.json` instead.
- The generated `.oxfmtrc.json` may not be formatted yet. Run `oxfmt` after migration.

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

Notes (Biome):

- For `formatter.*` options in the table, a `javascript.formatter.*` value of the same name takes precedence when present. `bracketSameLine` is read only from `javascript.formatter.bracketSameLine`.
- Options not set in `biome.json` are written to `.oxfmtrc.json` with Biome's default values explicitly (e.g. `printWidth: 80`, `useTabs: true`), so the output preserves Biome's formatting behavior.
- If no Biome config is found, creates a blank `.oxfmtrc.json` instead.
- `overrides` cannot be auto-migrated and must be converted manually (a warning is printed if detected).

Notes (both sources):

- Fails if an Oxfmt config (`.oxfmtrc.json`, `.oxfmtrc.jsonc`, `oxfmt.config.ts` or `oxfmt.config.mts`) already exists. Delete it first if you want to re-run.

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

Any option not in "Prettier-Compatible Options" below is skipped with a warning, including options of unsupported plugins (e.g. `importOrder`). Notable ones:

| Option                          | Status                                                                    |
| ------------------------------- | ------------------------------------------------------------------------- |
| 

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

apps/oxfmt/test/cli/config_symlink/fixtures/.oxfmtrc.json

apps/oxfmt/test/cli/config_symlink/fixtures/sub/.oxfmtrc.json

apps/oxfmt/test/cli/ignore_symlink/fixtures/bar.js

apps/oxfmt/test/lsp/format/fixtures/config-symlink/.oxfmtrc.json

apps/oxlint/fixtures/cli/ignore_patterns_symlink/testdir/.oxlintrc.json

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Migrate Oxfmt](https://modelsatlas.com/skills/oxc-project/migrate-oxfmt/badge.svg)](https://modelsatlas.com/skills/oxc-project/migrate-oxfmt/)

Not your listing, or something out of date? Claim or update your listing.