ESLint

O que é o ESLint?

O ESLint é um linter plugável para JavaScript e TypeScript. Ele analisa seu código transformando-o em uma árvore de sintaxe, executa um conjunto de regras sobre ela e reporta problemas. As regras variam desde a detecção de bugs reais — variáveis não utilizadas, await ausentes, igualdades inseguras — até convenções que sua equipe deseja aplicar.

O valor é cumulativo. Cada regra captura uma classe de erro uma única vez, em todos os lugares e para sempre, em vez de depender de revisores para notá-la. Muitas regras também possuem correção automática, então o eslint --fix limpa uma quantidade surpreendente de código automaticamente. O ESLint é uma das ferramentas de maior impacto em um projeto JavaScript.

Flat config

O ESLint utiliza o flat config: um arquivo que exporta um array de objetos de configuração. Ele substitui o formato antigo .eslintrc por imports explícitos e uma composição previsível.

// eslint.config.js
import js from "@eslint/js";
import tseslint from "typescript-eslint";

export default tseslint.config(
  { ignores: ["dist", "coverage", "**/*.generated.*"] },
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ["**/*.ts", "**/*.tsx"],
    rules: {
      "@typescript-eslint/no-floating-promises": "error",
    },
  },
);

Cada objeto pode especificar a quais arquivos ele se aplica, quais plugins registra e quais regras define. Objetos posteriores sobrescrevem os anteriores, portanto, o array é lido de cima para baixo, como uma cascata.

Regras e severidade

Cada regra possui uma severidade: "off", "warn" ou "error".

// rules.js
export default [
  {
    rules: {
      eqeqeq: "error",              // require ===
      "no-unused-vars": "warn",
      "no-console": ["warn", { allow: ["warn", "error"] }],
    },
  },
];

Algumas regras aceitam opções, como a no-console faz aqui. error falha no CI; warn reporta sem falhar. Use warn para regras que você está implementando gradualmente e error para qualquer coisa que deva bloquear um merge.

Plugins e presets

Plugins adicionam regras para ecossistemas específicos, e presets agrupam um conjunto selecionado delas.

// react.js
import react from "eslint-plugin-react";
import reactHooks from "eslint-plugin-react-hooks";

export default [
  react.configs.flat.recommended,
  reactHooks.configs["recommended-latest"],
];

Plugins comuns abrangem React, Vue, TypeScript, imports, bibliotecas de teste e acessibilidade. Começar com eslint:recommended mais um preset de framework entrega 90% do valor com quase nenhuma configuração. Adicione regras individuais apenas quando houver um motivo específico.

Linting com consciência de tipos (Type-aware linting)

typescript-eslint pode utilizar o verificador de tipos do TypeScript para regras que a análise sintática simples não consegue processar.

// type-aware.js
export default tseslint.config({
  languageOptions: {
    parserOptions: {
      projectService: true,
      tsconfigRootDir: import.meta.dirname,
    },
  },
  rules: {
    "@typescript-eslint/no-floating-promises": "error",
    "@typescript-eslint/no-misused-promises": "error",
  },
});

Regras como no-floating-promises capturam bugs que são genuinamente difíceis de notar apenas na leitura: como uma promise que nunca é aguardada (awaited). O linting com consciência de tipos é mais lento porque executa o verificador de tipos, por isso muitos projetos o habilitam para o código-fonte e o desativam para testes e arquivos de configuração.

Corrigindo e desativando

Muitas regras podem ser corrigidas automaticamente, portanto, execute o fixer antes de analisar a saída.

npx eslint . --fix

Quando você realmente precisar quebrar uma regra, desative-a de forma pontual e explique o motivo.

// targeted.js
// eslint-disable-next-line no-console -- intentional debug log
console.log("payment flow", payload);

Um /* eslint-disable */ genérico no topo de um arquivo desativa tudo, incluindo as regras que teriam detectado bugs reais. Prefira a desativação em uma única linha com a justificativa e ajuste a configuração caso uma regra conflite com seus padrões.

Editores e CI

Instale a extensão do ESLint no seu editor e ative a opção de correção ao salvar (fix-on-save). Assim, você recebe feedback enquanto digita e as correções seguras são aplicadas imediatamente, transformando o linting em parte do fluxo de edição em vez de uma tarefa tediosa. No CI, execute o ESLint como uma etapa separada para que as falhas sejam claras e rápidas, e faça o cache dos resultados sempre que possível.

Onde o ESLint se encaixa

O ESLint cuida da qualidade do código; o Prettier cuida da formatação. A configuração padrão é deixar o Prettier responsável pelo estilo e desativar as regras do ESLint que conflitem, geralmente utilizando uma config compartilhada. Juntos, eles garantem que os revisores discutam o design em vez de espaçamentos e pontos e vírgulas.

Melhores práticas

• Comece com eslint:recommended e um preset de framework, e então adicione regras deliberadamente.
• Use flat config com imports explícitos e uma lista de ignores clara.
• Deixe o Prettier cuidar da formatação e desative as regras do ESLint que causem conflito.
• Execute --fix antes de triar os problemas restantes.
• Ative regras type-aware para os arquivos de código-fonte.
• Desative regras de forma pontual, com um comentário explicando o motivo.
• Execute o lint no editor, em um pre-commit hook e na CI.

Erros comuns

• Fazer o linting de dist, código gerado e dependências.
• Desativar regras indiscriminadamente em vez de corrigir a causa raiz.
• Ativar todas as regras de uma vez e se perder no excesso de alertas.
• Duplicar regras de formatação que o Prettier já resolve.
• Executar linting com análise de tipos (type-aware) em todo o repositório, tornando-o lento.
• Tratar warnings como inofensivos até que eles se acumulem.

Próximos passos

O ESLint é o guardião da qualidade do seu código. Combine-o com o Prettier para formatação, aprofunde a tipagem com TypeScript e integre-o ao build do Vite e ao seu pipeline de CI. Depois, ative uma nova regra e corrija cada ocorrência — é um pequeno hábito com um grande retorno.