Migrar do ESLint

Para projetos JS/TS que hoje usam ESLint e querem migrar para Oxlint.

Visão geral

Oxlint e ESLint compartilham ideias de configuração, mas diferem em regras e formato de arquivo.

O Oxlint já cobre mais de 700 regras do núcleo ESLint e de plugins populares; a intenção é cobrir quase todas as do núcleo — trabalho em andamento. Veja a matriz de compatibilidade para frameworks e tipos de arquivo.

Ao migrar:

• A maioria das regras do núcleo e de plugins está disponível
• Algumas regras ainda não existem
• Arquivos ESLint precisam virar o formato Oxlint
• Adoção incremental é o desenho — não precisa migrar tudo de uma vez
• Plugins JS permitem reaproveitar plugins ESLint ainda não nativos

Migrar com Skills

Fluxo interativo com a skill migrate-oxlint:

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

Depois use /migrate-oxlint e o agente guia a migração.

Flat config do ESLint (v9/v10)

Com eslint.config.js / eslint.config.mjs, use @oxlint/migrate.

Rodar a ferramenta

Na raiz:

npx @oxlint/migrate <caminho-opcional-flat-config>

O comando:

• Lê o flat config
• Converte regras suportadas para Oxlint
• Mantém severidades e opções
• Mantém overrides por caminho
• Converte globals (ex.: ...globals.browser) para env / globals
• Preserva padrões ignore da raiz

O .oxlintrc.json gerado pode ser editado depois.

.eslintignore continua respeitado; o ideal é mover o conteúdo para ignorePatterns no .oxlintrc.json após migrar. .gitignore do repositório também é respeitado.

Opções: readme do oxlint-migrate.

Regras TypeScript conscientes de tipo

Se você usava typescript-eslint com tipo, passe --type-aware para incluir essas regras na config gerada.

Lint com tipos depende de oxlint-tsgolint e da reescrita nativa do TypeScript (TypeScript 7), mas costuma ser viável na maioria dos projetos.

Detalhes: Lint com tipos.

Plugins JavaScript

Plugins ainda não nativos podem seguir via plugins JS; @oxlint/migrate migra isso por padrão.

A maioria dos plugins focados em JS/TS deve funcionar; o suporte à API ESLint v9 no Oxlint é grande e melhora com o tempo.

Para não migrar plugins como JS plugins: --js-plugins=false.

Mais: Plugins JS.

Plugins ESLint locais da empresa

Imports locais (ex.: ./eslint-plugin-my-company) ainda não migram sozinhos; adicione manualmente após o script:

.oxlintrc.json

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "jsPlugins": ["./eslint-plugin-company/lib/index.js"]
}

oxlint.config.ts

import { defineConfig } from "oxlint";

export default defineConfig({
  jsPlugins: ["./eslint-plugin-company/lib/index.js"],
});

Rodar Oxlint e ESLint juntos

Enquanto faltarem regras no Oxlint:

1. Oxlint para o que já cobre
2. ESLint para o que falta
3. Desative no ESLint as regras que o Oxlint já cobre

Oxlint é bem mais rápido — rode primeiro.

oxlint && eslint

Evitar duplicata no ESLint

eslint-plugin-oxlint desliga no ESLint as regras já cobertas pelo Oxlint:

npm install --save-dev eslint-plugin-oxlint

Menos diagnósticos duplicados, lint mais rápido no ESLint. No longo prazo, migrar 100% para Oxlint simplifica dependências.

Legacy ESLint v8 (.eslintrc)

@oxlint/migrate não lê .eslintrc.js / .eslintrc.json direto.

Às vezes dá para converter para flat com @eslint/migrate-config e depois usar @oxlint/migrate.

O formato “legacy” v8 é parecido com o Oxlint — em setups simples regras e opções traduzem quase direto.

Suporte de regras/plugins

Para regras críticas ainda não portadas: meta issue #481.

Plugins não nativos: use Plugins JS.