Configuração

O Oxlint funciona sem config, mas a maioria dos times versiona .oxlintrc.json ou oxlint.config.ts para alinhar lint local, editores e CI.

Esta página cobre configuração de projeto: regras, categorias, plugins, overrides e configurações compartilhadas.

Criar arquivo de config

Gerar starter JSON no diretório atual:

oxlint --init

O Oxlint procura .oxlintrc.json ou oxlint.config.ts no diretório de trabalho. Também pode passar config explicitamente (isso desativa busca de config aninhada):

oxlint -c ./oxlintrc.json
# ou
oxlint --config ./oxlintrc.json

Observações:

.oxlintrc.json aceita comentários (como jsonc).
O formato busca compatibilidade com ESLint v8 (eslintrc.json).
Em um diretório use .oxlintrc.json ou oxlint.config.ts, não os dois.

Exemplo mínimo:

.oxlintrc.json

json

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

Arquivo TypeScript (`oxlint.config.ts`)

oxlint.config.ts

import { defineConfig } from "oxlint";

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

Observações:

O arquivo deve se chamar oxlint.config.ts (também ao passar com --config).
O export default deve ser um objeto; defineConfig ajuda nos tipos.
Config TS exige pacote Node oxlint. Binário standalone: use só .oxlintrc.json.
Node capaz de executar TypeScript (v22.18+ ou v24+).

Formato do arquivo

JSON (.oxlintrc.json) ou módulo TS que export default do objeto (oxlint.config.ts). Campos comuns:

rules: ligar/desligar regras, severidade, opções.
categories: grupos de regras por intenção.
plugins: plugins nativos.
jsPlugins: plugins JavaScript (alfa).
overrides: config por glob de arquivos.
extends: herdar de outros arquivos.
ignorePatterns: ignorar arquivos adicionais.
env: globais pré-definidas por ambiente.
globals: globais customizadas (somente leitura / gravável).
settings: config compartilhada entre regras de um plugin.
options: opções do linter (typeAware, typeCheck, etc.).

Lista completa: Referência do arquivo de config.

Opções do linter (`options`)

Ver referência — options.

.oxlintrc.jsonoxlint.config.ts

json

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

import { defineConfig } from "oxlint";

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

options.typeAware equivale a --type-aware na CLI.
options.typeCheck (experimental) equivale a --type-check.
options.maxWarnings equivale a --max-warnings.

Flags CLI sobrepõem valores da config quando ambos existem.

options.typeAware e options.typeCheck só na config raiz.

Configurar regras

Tudo sob rules.

Valor da regra:

severidade ("off", "warn", "error"), ou
array [severidade, opções].

Regra do núcleo ESLint com nome único pode ficar sem prefixo: no-console = eslint/no-console.

.oxlintrc.jsonoxlint.config.ts

json

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

import { defineConfig } from "oxlint";

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

Severidades

Desligar: "off" ou "allow"
Aviso: "warn"
Erro: "error" ou "deny"

Opções de regra

Use array [severidade, opções]:

.oxlintrc.jsonoxlint.config.ts

json

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

import { defineConfig } from "oxlint";

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

Todas as regras e opções: Referência de regras.

Severidade só na CLI

Experimentos rápidos:

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

Ordem da esquerda para a direita:

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

Categorias

Categorias ligam/desligam conjuntos de regras. Por padrão, correctness fica ligada.

.oxlintrc.jsonoxlint.config.ts

json

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

import { defineConfig } from "oxlint";

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

Categorias:

correctness: código claramente errado ou inútil
suspicious: provavelmente errado ou inútil
pedantic: regras extras, podem gerar falsos positivos
perf: desempenho em runtime
style: estilo idiomático
restriction: proíbe padrões/recursos específicos
nursery: em desenvolvimento; podem mudar

CLI com -A/-W/-D nas categorias:

oxlint -D correctness -D suspicious

Plugins nativos

Ampliam o conjunto de regras. Implementações em Rust cobrem bastante sem árvore enorme em JS — Plugins embutidos.

plugins substitui o conjunto padrão — liste tudo que quiser ligado:

.oxlintrc.jsonoxlint.config.ts

json

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

import { defineConfig } from "oxlint";

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

Para desligar todos os padrões:

.oxlintrc.jsonoxlint.config.ts

json

{
  "plugins": []
}

import { defineConfig } from "oxlint";

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

Flags como --import-plugin: Plugins embutidos.

Plugins JS (alfa)

jsPlugins para compatibilidade com plugins ESLint e integrações avançadas.

Em alfa — sem garantia semver.

Strings ou objeto com alias:

.oxlintrc.jsonoxlint.config.ts

json

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

import { defineConfig } from "oxlint";

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

Nomes reservados (nativos em Rust): react, unicorn, typescript, oxc, import, jest, vitest, jsx-a11y, nextjs etc. Precisa da versão JS de um nome reservado? use name customizado.

Detalhes: Plugins JS.

Overrides por padrão de arquivo

overrides: array — testes, scripts, só TS etc.

Cada item pode ter:

files: globs
rules: como rules de nível superior
env / globals: mesmo formato do topo
plugins: substituir plugins só nesse conjunto de arquivos
jsPlugins: plugins JS no override

.oxlintrc.jsonoxlint.config.ts

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"
      }
    }
  ]
}

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`

Herança de outros arquivos. Caminhos relativos ao arquivo que declara extends. Merge na ordem; entradas posteriores sobrepõem anteriores.

.oxlintrc.jsonoxlint.config.ts

json

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

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

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

Ambientes e globais

env: globais de ambientes comuns (browser, node…).

globals: globais do projeto — somente leitura, gravável ou desativadas.

.oxlintrc.jsonoxlint.config.ts

json

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

import { defineConfig } from "oxlint";

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

globals:

"readonly" / "readable" / false
"writable" / "writeable" / true
"off" desliga uma global que viria por outro lado

`settings`

Config por plugin compartilhada entre várias regras.

Exemplo monorepo + React + jsx-a11y:

.oxlintrc.jsonoxlint.config.ts

json

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

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",
      },
    },
  },
});

Próximos passos

Ignorar arquivos: padrões, .gitignore, .eslintignore, symlinks.
Comentários de ignore: supressões inline e exceções.
Configs aninhadas: monorepos e pacotes.
Referência do arquivo de config: schema e campos.
Referência CLI: flags e formatos de saída.

Configuração ​

Criar arquivo de config ​

Arquivo TypeScript (oxlint.config.ts) ​

Formato do arquivo ​

Opções do linter (options) ​

Configurar regras ​

Severidades ​

Opções de regra ​

Severidade só na CLI ​

Categorias ​

Plugins nativos ​

Plugins JS (alfa) ​

Overrides por padrão de arquivo ​

extends ​

Ambientes e globais ​

settings ​

Próximos passos ​

Configuração

Criar arquivo de config

Arquivo TypeScript (`oxlint.config.ts`)

Formato do arquivo

Opções do linter (`options`)

Configurar regras

Severidades

Opções de regra

Severidade só na CLI

Categorias

Plugins nativos

Plugins JS (alfa)

Overrides por padrão de arquivo

`extends`

Ambientes e globais

`settings`

Próximos passos