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

Oxlint работает из коробки, но команды обычно коммитят файл конфигурации (.oxlintrc.json или oxlint.config.ts), чтобы линт был единообразен локально, в редакторах и CI.

Здесь — про конфигурацию проекта: правила, категории, плагины, overrides и общие настройки.

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

Стартовый конфиг в текущей директории (JSON):

oxlint --init

Oxlint ищет .oxlintrc.json или oxlint.config.ts в текущем каталоге. Можно явно указать конфиг (при этом отключается поиск вложенных конфигов):

oxlint -c ./oxlintrc.json
# или
oxlint --config ./oxlintrc.json

Замечания:

• В .oxlintrc.json поддерживаются комментарии (как в jsonc).
• Формат ориентирован на совместимость с ESLint v8 (eslintrc.json).
• В одной директории используйте либо .oxlintrc.json, либо oxlint.config.ts, не оба сразу.

Минимальный пример:

.oxlintrc.json

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "categories": {
    "correctness": "warn"
  },
  "rules": {
    "eslint/no-unused-vars": "error"
  }
}

TypeScript-конфиг (oxlint.config.ts)

Поддерживается файл oxlint.config.ts.

oxlint.config.ts

import { defineConfig } from "oxlint";

export default defineConfig({
  categories: {
    correctness: "warn",
  },
  rules: {
    "eslint/no-unused-vars": "error",
  },
});

Замечания:

• Имя файла должно быть oxlint.config.ts (в том числе при передаче через --config).
• Экспорт по умолчанию — объект, желательно обёрнутый в defineConfig для типов.
• TypeScript-конфиги требуют npm-пакет oxlint (JS runtime). Для standalone-бинарника используйте .oxlintrc.json.
• Нужен Node, который выполняет TypeScript (Node v22.18+ или v24+).

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

Файл — либо JSON-объект (.oxlintrc.json), либо TS-модуль с экспортом по умолчанию (oxlint.config.ts). Типичные поля верхнего уровня:

• rules: включение/выключение правил, строгость, опции.
• categories: группы правил с общим смыслом.
• plugins: встроенные плагины с дополнительными правилами.
• jsPlugins: JavaScript-плагины (alpha).
• overrides: разная конфигурация для разных шаблонов файлов.
• extends: наследование от других файлов.
• ignorePatterns: дополнительные игноры из конфига.
• env: предопределённые глобалы для сред.
• globals: пользовательские глобалы read-only / writable.
• settings: общие для плагина настройки, которыми пользуются несколько правил.
• options: опции уровня линтера (например options.typeAware и options.typeCheck).

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

Опции линтера

Поведение на уровне всего линтера — в options. Полный список — в справочнике.

Пример:

.oxlintrc.json

{
  "options": {
    "typeAware": true,
    "typeCheck": true,
    "maxWarnings": 10
  }
}

oxlint.config.ts

import { defineConfig } from "oxlint";

export default defineConfig({
  options: {
    typeAware: true,
    typeCheck: true,
    maxWarnings: 10,
  },
});

• options.typeAware эквивалентно --type-aware в CLI.
• options.typeCheck (эксперимент) эквивалентно --type-check в CLI.
• options.maxWarnings эквивалентно --max-warnings в CLI.

При конфликте приоритет у флагов CLI.

options.typeAware и options.typeCheck только в корневом конфиге.

Настройка правил

Правила задаются в rules.

Значение правила:

• строгость ("off", "warn", "error"), или
• массив [severity, options]

Для правил из ядра ESLint с уникальным именем префикс плагина не обязателен: no-console то же, что eslint/no-console.

.oxlintrc.json

{
  "rules": {
    "no-alert": "error",
    "oxc/approx-constant": "warn",
    "no-plusplus": "off",
    "eslint/prefer-const": ["error", { "destructuring": "any" }]
  }
}

oxlint.config.ts

import { defineConfig } from "oxlint";

export default defineConfig({
  rules: {
    "no-alert": "error",
    "oxc/approx-constant": "warn",
    "no-plusplus": "off",
    "eslint/prefer-const": ["error", { destructuring: "any" }],
  },
});

Значения строгости

В духе ESLint:

• Отключить: "off" или "allow"
• Предупреждение: "warn"
• Ошибка: "error" или "deny"

Опции правил

Опции — через массив:

.oxlintrc.json

{
  "rules": {
    "no-plusplus": ["error", { "allowForLoopAfterthoughts": true }]
  }
}

oxlint.config.ts

import { defineConfig } from "oxlint";

export default defineConfig({
  rules: {
    "no-plusplus": ["error", { allowForLoopAfterthoughts: true }],
  },
});

Список правил и опций — в справочнике правил.

Строгость из CLI

Для экспериментов:

• -A / --allow
• -W / --warn
• -D / --deny

Применяются слева направо:

oxlint -D no-alert -W oxc/approx-constant -A no-plusplus

Категории правил

Категории включают или отключают наборы правил с общей целью. По умолчанию Oxlint включает категорию correctness.

Настройка через categories:

.oxlintrc.json

{
  "categories": {
    "correctness": "error",
    "suspicious": "warn",
    "pedantic": "off"
  }
}

oxlint.config.ts

import { defineConfig } from "oxlint";

export default defineConfig({
  categories: {
    correctness: "error",
    suspicious: "warn",
    pedantic: "off",
  },
});

Доступные категории:

• correctness: явно ошибочный или бесполезный код
• suspicious: код, который с высокой вероятностью ошибочен или бесполезен
• pedantic: очень строгие правила, возможны ложные срабатывания
• perf: производительность во время выполнения
• style: идиоматический единый стиль
• restriction: запрет отдельных приёмов или возможностей языка
• nursery: правила в разработке, могут меняться

Категории можно задавать в CLI теми же -A, -W, -D:

oxlint -D correctness -D suspicious

Плагины

Плагины расширяют набор правил.

Многие популярные плагины реализованы в Rust в Oxlint — широкое покрытие без тяжёлого дерева JS-зависимостей. См. Встроенные плагины.

Поле plugins заменяет набор плагинов по умолчанию — перечислите все нужные:

.oxlintrc.json

{
  "plugins": ["unicorn", "typescript", "oxc"]
}

oxlint.config.ts

import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["unicorn", "typescript", "oxc"],
});

Отключить все плагины по умолчанию:

.oxlintrc.json

{
  "plugins": []
}

oxlint.config.ts

import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: [],
});

Детали и флаги CLI вроде --import-plugin — на странице Встроенные плагины.

JS-плагины (alpha)

Через jsPlugins — для совместимости с ESLint-плагинами и продвинутых сценариев.

Замечания:

• JS-плагины в alpha, semver не гарантируется.

Строки или объекты с псевдонимом:

.oxlintrc.json

{
  "jsPlugins": [
    "eslint-plugin-playwright",
    { "name": "my-eslint-react", "specifier": "eslint-plugin-react" }
  ]
}

oxlint.config.ts

import { defineConfig } from "oxlint";

export default defineConfig({
  jsPlugins: [
    "eslint-plugin-playwright",
    { name: "my-eslint-react", specifier: "eslint-plugin-react" },
  ],
});

Имена вроде react, unicorn, typescript, oxc, import, jest, vitest, jsx-a11y, nextjs зарезервированы под нативную реализацию. Нужна JS-версия — задайте свой name.

Подробнее — JS-плагины.

Конфигурация по шаблону файлов

overrides — разные настройки для тестов, скриптов, только TypeScript и т.д.

Каждый элемент может содержать:

• files: glob-шаблоны
• rules: как верхний уровень rules
• env, globals: как на верхнем уровне
• plugins: сменить список плагинов для этого override
• jsPlugins: JS-плагины для override (alpha)

Пример:

.oxlintrc.json

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "rules": {
    "no-console": "error"
  },
  "overrides": [
    {
      "files": ["scripts/*.js"],
      "rules": {
        "no-console": "off"
      }
    },
    {
      "files": ["**/*.{ts,tsx}"],
      "plugins": ["typescript"],
      "rules": {
        "typescript/no-explicit-any": "error"
      }
    },
    {
      "files": ["**/test/**"],
      "plugins": ["jest"],
      "env": {
        "jest": true
      },
      "rules": {
        "jest/no-disabled-tests": "off"
      }
    }
  ]
}

oxlint.config.ts

import { defineConfig } from "oxlint";

export default defineConfig({
  rules: {
    "no-console": "error",
  },
  overrides: [
    {
      files: ["scripts/*.js"],
      rules: {
        "no-console": "off",
      },
    },
    {
      files: ["**/*.{ts,tsx}"],
      plugins: ["typescript"],
      rules: {
        "typescript/no-explicit-any": "error",
      },
    },
    {
      files: ["**/test/**"],
      plugins: ["jest"],
      env: {
        jest: true,
      },
      rules: {
        "jest/no-disabled-tests": "off",
      },
    },
  ],
});

Общие конфиги (extends)

extends подключает другие файлы конфигурации.

Пути разрешаются относительно файла с extends. Слияние идёт по порядку массива, последующие перекрывают предыдущие.

.oxlintrc.json

{
  "extends": ["./configs/base.json", "./configs/frontend.json"]
}

oxlint.config.ts

import baseConfig from "./configs/base.ts";
import frontendConfig from "./configs/frontend.ts";
import { defineConfig } from "oxlint";

export default defineConfig({
  extends: [baseConfig, frontendConfig],
});

Среды и глобалы

env — готовые наборы глобалов (browser, node и т.д.).

globals — свои глобалы, writable/readonly или отключение глобала, который иначе был бы доступен.

.oxlintrc.json

{
  "env": {
    "es6": true
  },
  "globals": {
    "MY_GLOBAL": "readonly",
    "Promise": "off"
  }
}

oxlint.config.ts

import { defineConfig } from "oxlint";

export default defineConfig({
  env: {
    es6: true,
  },
  globals: {
    MY_GLOBAL: "readonly",
    Promise: "off",
  },
});

globals допускает:

• "readonly" / "readable" / false
• "writable" / "writeable" / true
• "off" — отключить глобал

Настройки плагинов (settings)

Общие для плагина параметры, которыми пользуются несколько правил.

Пример (монорепо + React + jsx-a11y):

.oxlintrc.json

{
  "settings": {
    "next": {
      "rootDir": "apps/dashboard/"
    },
    "react": {
      "linkComponents": [{ "name": "Link", "linkAttribute": "to" }]
    },
    "jsx-a11y": {
      "components": {
        "Link": "a",
        "Button": "button"
      }
    }
  }
}

oxlint.config.ts

import { defineConfig } from "oxlint";

export default defineConfig({
  settings: {
    next: {
      rootDir: "apps/dashboard/",
    },
    react: {
      linkComponents: [{ name: "Link", linkAttribute: "to" }],
    },
    "jsx-a11y": {
      components: {
        Link: "a",
        Button: "button",
      },
    },
  },
});

Дальше

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