Миграция с Prettier

В этом руководстве описан переход с Prettier на Oxfmt.

Быстрый старт

Для простых конфигураций достаточно одной команды:

npm

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

pnpm

$ pnpm add -D oxfmt@latest && pnpm oxfmt --migrate=prettier && pnpm oxfmt

yarn

$ yarn add -D oxfmt@latest && yarn oxfmt --migrate=prettier && yarn oxfmt

bun

$ bun add -D oxfmt@latest && bunx oxfmt --migrate=prettier && bunx oxfmt

Миграция через Skills

Интерактивную миграцию можно выполнить с помощью навыка migrate-oxfmt:

npx skills add https://github.com/oxc-project/oxc --skill migrate-oxfmt

После установки выполните /migrate-oxfmt — агент проведёт вас через полную миграцию.

Перед миграцией

Oxfmt совместим с конфигурациями Prettier v3.8 во многих случаях.

Основные отличия:

• По умолчанию printWidth равен 100 (у Prettier — 80)
• Плагины Prettier не поддерживаются (часть популярных реализована нативно)
• Некоторые опции не поддерживаются (см. справочник конфигурации)

Подробности см. в разделе Неподдерживаемые возможности и в матрице совместимости.

Шаг 1: Обновить Prettier до v3.8 (необязательно)

Вывод Oxfmt ближе всего к Prettier v3.8. Обновление заранее уменьшает расхождения форматирования.

Шаг 2: Установить Oxfmt

npm

$ npm add -D oxfmt@latest

pnpm

$ pnpm add -D oxfmt@latest

yarn

$ yarn add -D oxfmt@latest

bun

$ bun add -D oxfmt@latest

deno

$ deno add -D npm:oxfmt@latest

Шаг 3: Перенести конфигурацию

Oxfmt использует .oxfmtrc.json, .oxfmtrc.jsonc или oxfmt.config.ts. Простой пример:

.oxfmtrc.jsonc

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

Выполните oxfmt --migrate prettier, чтобы автоматически преобразовать конфиг Prettier.

Пример prettierrc.js

До:

prettierrc.js

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

После (oxfmt.config.ts):

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  singleQuote: true,
  jsxSingleQuote: true,
  printWidth: 80,
});

Пример prettierrc.yaml

До:

prettierrc.yaml

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

После (.oxfmtrc.jsonc):

.oxfmtrc.jsonc

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

Шаг 4: Обновить скрипты

Скрипты в package.json

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

CI-воркфлоу

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

Git-хуки (husky, lint-staged)

В package.json:

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

Шаг 5: Запустить форматтер

npm run format

Если Prettier больше не нужен, удалите его.

Дополнительные шаги

Обновить интеграции с редакторами

См. Настройку редакторов.

Обновить документацию

При необходимости замените упоминания Prettier в CONTRIBUTING.md, AGENTS.md и CLAUDE.md.

Обновить правила линтера

Удалите eslint-plugin-prettier, если он используется. При необходимости его можно заменить шагом oxfmt --check в CI.

Если вы продолжаете использовать ESLint, рекомендуется оставить или добавить eslint-config-prettier, чтобы отключить стилевые правила ESLint, конфликтующие с Oxfmt. eslint-config-prettier отличается от eslint-plugin-prettier: это только конфигурация, без новых правил линтера.

Также рассмотрите переход на Oxlint.

Обновить .git-blame-ignore-revs

Добавьте SHA коммита массового переформатирования в .git-blame-ignore-revs, чтобы скрыть его из git blame.

Заменить .prettierignore на "ignorePatterns"

Если Prettier больше не используется, можно перенести содержимое .prettierignore в "ignorePatterns" конфигурации Oxfmt. Учтите: .prettierignore действует глобально, а ignorePatterns ограничен файлом конфигурации. При вложенной конфигурации список игнорируемых файлов может измениться. Подробнее см. Игнорируемые файлы.