Конфигурация

Oxfmt работает из коробки, но многие команды коммитят файл конфигурации, чтобы форматирование совпадало локально, в редакторе и в CI.

Здесь описана конфигурация проекта: опции форматирования, шаблоны игнора и экспериментальные возможности.

Создание файла конфигурации

Чтобы создать стартовый конфиг в текущем каталоге:

oxfmt --init

Oxfmt ищет следующие файлы, начиная с каталога форматируемого файла и поднимаясь вверх по дереву:

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

Выигрывает ближайший к каждому файлу конфиг. Так можно размещать разные конфиги на разных уровнях дерева. Например, корневой конфиг для всего репозитория и отдельный для подкаталога:

my-repo/
├── oxfmt.config.ts         # по умолчанию для всего репо
├── src/
│   └── app.ts              # использует корневой конфиг
└── packages/
    └── fancy-app/
        ├── .oxfmtrc.json   # переопределения для этого пакета
        └── index.ts        # использует packages/fancy-app/.oxfmtrc.json

Если вложенная конфигурация не нужна, передайте --disable-nested-config: поиск только вверх от текущего рабочего каталога. Это быстрее — конфиг можно разрешить один раз, а не для каждого файла.

Явный конфиг через -c также отключает поиск вложенных конфигов. Поддерживаются форматы .json, .jsonc, .ts, .mts, .cts, .js, .mjs, .cjs:

oxfmt -c path/to/yourconfig.json

Минимальный JSON-конфиг:

.oxfmtrc.json

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

В JS/TS-конфигах используется экспорт по умолчанию. defineConfig необязателен, но даёт проверку типов и автодополнение в редакторе:

oxfmt.config.ts

import { defineConfig } from "oxfmt";

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

Формат файла конфигурации

Конфигурация — это JSON-объект. Частые поля верхнего уровня:

• printWidth: ограничение длины строки (по умолчанию: 100)
• tabWidth: пробелов на уровень отступа (по умолчанию: 2)
• useTabs: табы вместо пробелов (по умолчанию: false)
• semi: точки с запятой (по умолчанию: true)
• singleQuote: одинарные кавычки (по умолчанию: false)
• trailingComma: висячие запятые в многострочных конструкциях (по умолчанию: "all")
• ignorePatterns: glob-шаблоны исключения из форматирования
• sortImports: настройка сортировки импортов (по умолчанию выключено)
• sortTailwindcss: сортировка классов Tailwind (по умолчанию выключено)
• sortPackageJson: сортировка package.json (по умолчанию включено)

Полный список полей см. в справочнике конфигурации.

JSON Schema

Добавьте поле $schema для проверки и автодополнения в редакторе:

.oxfmtrc.json

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

.editorconfig

Oxfmt читает свойства .editorconfig:

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

Поддерживаются корневая секция и переопределения по glob.

[*]
indent_size = 4

[*.{js,ts}]
indent_size = 2

Oxfmt использует только ближайший .editorconfig от текущего каталога:

• root = true не учитывается
• Вложенные .editorconfig не сливаются

Переопределения (overrides)

Поле overrides задаёт разные опции для разных файлов:

.oxfmtrc.json

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

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 100,
  overrides: [
    {
      files: ["*.test.js", "*.spec.ts"],
      options: {
        printWidth: 120,
      },
    },
    {
      files: ["*.md", "*.html"],
      excludeFiles: ["*.min.js"],
      options: {
        tabWidth: 4,
      },
    },
  ],
});

У каждой записи:

• files (обязательно): glob-шаблоны файлов
• excludeFiles (необязательно): glob-исключения для этого переопределения
• options: применяемые опции форматирования

Glob-шаблоны считаются относительно каталога с файлом конфигурации Oxfmt.

Приоритет

Опции применяются в порядке (от меньшего приоритета к большему):

1. Значения по умолчанию
2. Корневые опции конфигурации
3. Опции из overrides
4. Для незаданных полей — поддерживаемые опции из .editorconfig

Специфичные для Oxfmt опции

insertFinalNewline

Управляет добавлением финального перевода строки в отформатированные файлы. По умолчанию true.

Это часто запрашиваемая возможность Prettier: в некоторых окружениях (например Salesforce) хвостовые переводы строк удаляются.

printWidth

У Oxfmt по умолчанию printWidth: 100 (у Prettier — 80). Причины:

• код на TypeScript длиннее из‑за аннотаций типов
• в импортах часто много спецификаторов
• экраны стали шире
• меньше переносов — меньше токенов для LLM

Чтобы совпасть с Prettier по умолчанию:

.oxfmtrc.json

{
  "printWidth": 80
}

oxfmt.config.ts

import { defineConfig } from "oxfmt";

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

Дальнейшие шаги

• Игнорируемые файлы: шаблоны игнора, .gitignore и .prettierignore.
• Встроенные комментарии игнорирования: точечное отключение форматирования.
• Справочник конфигурации: полная схема и описание полей.
• Справочник CLI: полный список флагов.