Regras Essenciais do ESLint

Q: Qual a diferença entre os níveis de severidade "off", "warn" e "error"?

"off" (0) desabilita a regra completamente. "warn" (1) mostra um aviso amarelo, mas não falha a CI ou bloqueia builds. "error" (2) mostra um erro vermelho, falha a CI e bloqueia builds.

Q: Por que devo usar @typescript-eslint/no-unused-vars em vez do no-unused-vars base?

O no-unused-vars base do ESLint não entende a sintaxe do TypeScript (interfaces, type aliases, enums). As duas regras entram em conflito quando ambas estão habilitadas. Desative a regra base e use apenas a versão do TypeScript:

Q: Armadilha: Por que import/order não auto-corrige completamente na primeira execução?

eslint --fix pode reordenar imports dentro dos grupos. Ele nem sempre adiciona linhas em branco ausentes entre os grupos retroativamente. Execute eslint --fix uma vez, depois adicione manualmente linhas em branco na passagem inicial.

Q: Quando devo usar "warn" versus "error" para uma regra?

Use "warn" para regras para as quais você está migrando ou que são consultivas. Use "error" para regras que você deseja impor estritamente na CI. Lembre-se: "warn" não falhará a CI, então as violações se acumulam silenciosamente se você esquecer de promover para "error".

Q: O que react-hooks/exhaustive-deps detecta?

Dependências ausentes nos arrays de dependência de useEffect, useMemo e useCallback. Adicionar todas as dependências evita bugs de closure obsoleto. Definido como "warn" porque pode produzir falsos positivos com referências estáveis como dispatch.

Q: O que react/jsx-no-target-blank protege contra?

Links com target="_blank" sem rel="noreferrer" expõem sua página a ataques de window.opener. A regra impõe a adição de rel="noreferrer" a todos os links externos.

Configure as regras ESLint mais impactantes para React, hooks, TypeScript, imports e acessibilidade.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// Severity levels
"off"   // 0 - disable the rule
"warn"  // 1 - yellow warning, does not fail CI
"error" // 2 - red error, fails CI and blocks builds
 
// Common pattern: override a rule
{
  rules: {
    "rule-name": "error",
    "rule-name": ["error", { option: "value" }],
  },
}

Quando usar isso: Quando os presets padrão são muito permissivos ou muito rigorosos e você precisa ajustar regras específicas.

Exemplo de Trabalho

// eslint.config.mjs
import { FlatCompat } from "@eslint/eslintrc";
import { dirname } from "path";
import { fileURLToPath } from "url";
 
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
 
const compat = new FlatCompat({ baseDirectory: __dirname });
 
const eslintConfig = [
  ...compat.extends("next/core-web-vitals", "next/typescript"),
  {
    rules: {
      // --- React rules ---
      "react/jsx-no-target-blank": "error",
      "react/no-unescaped-entities": "off",
      "react/self-closing-comp": "warn",
      "react/jsx-curly-brace-presence": [
        "warn",
        { props: "never", children: "never" },
      ],
 
      // --- Hooks rules ---
      "react-hooks/rules-of-hooks": "error",
      "react-hooks/exhaustive-deps": "warn",
 
      // --- TypeScript rules ---
      "@typescript-eslint/no-unused-vars": [
        "error",
        {
          argsIgnorePattern: "^_",
          varsIgnorePattern: "^_",
          caughtErrorsIgnorePattern: "^_",
        },
      ],
      "@typescript-eslint/no-explicit-any": "warn",
      "@typescript-eslint/consistent-type-imports": [
        "error",
        { prefer: "type-imports" },
      ],
 
      // --- Import rules ---
      "import/order": [
        "warn",
        {
          groups: [
            "builtin",
            "external",
            "internal",
            ["parent", "sibling"],
            "index",
            "type",
          ],
          "newlines-between": "always",
          alphabetize: { order: "asc", caseInsensitive: true },
        },
      ],
      "import/no-duplicates": "error",
 
      // --- Accessibility rules ---
      "jsx-a11y/alt-text": "error",
      "jsx-a11y/anchor-is-valid": "warn",
    },
  },
];
 
export default eslintConfig;

O que isso demonstra:

Regras organizadas por categoria: React, hooks, TypeScript, imports, acessibilidade
Mistura de severidades error (precisa corrigir) e warn (deve corrigir)
Ignorando variáveis não utilizadas prefixadas com _ com base em padrão
Ordenação de imports com separação de grupos e ordenação alfabética

Mergulho Profundo

Como Funciona

Cada regra tem um nível de severidade: "off", "warn", ou "error"
Regras podem aceitar opções como segundo elemento de um array: ["error", { option: true }]
O preset next/core-web-vitals já habilita muitas regras - você as sobrescreve na sua própria configuração
Regras de plugins são prefixadas com o nome do plugin (ex: react/, @typescript-eslint/)

Variações

Regras do React que valem a pena conhecer:

Regra	O que Detecta
`react/jsx-no-target-blank`	Falta de `rel="noreferrer"` em links com `target="_blank"`
`react/no-unescaped-entities`	`'` ou `"` não escapados em texto JSX
`react/self-closing-comp`	`<div></div>` em vez de `<div />` para elementos vazios
`react/jsx-curly-brace-presence`	`{"string"}` desnecessário em vez de `string` no JSX
`react/no-array-index-key`	Uso do índice do array como `key` prop

Regras de Hooks:

Regra	O que Detecta
`react-hooks/rules-of-hooks`	Hooks chamados condicionalmente ou em loops
`react-hooks/exhaustive-deps`	Dependências ausentes em useEffect, useMemo, useCallback

Regras do TypeScript que valem a pena habilitar:

Regra	O que Detecta
`@typescript-eslint/no-unused-vars`	Variáveis declaradas mas não utilizadas
`@typescript-eslint/no-explicit-any`	Uso do tipo `any`
`@typescript-eslint/consistent-type-imports`	Falta da palavra-chave `type` em imports apenas de tipo
`@typescript-eslint/no-non-null-assertion`	Uso da asserção não nula `!`
`@typescript-eslint/prefer-nullish-coalescing`	Uso do OR lógico em vez de `??`

Notas do TypeScript

// consistent-type-imports enforces this:
import type { User } from "@/types"; // type-only import
import { fetchUser } from "@/lib/api"; // value import
 
// Instead of mixing them:
import { User, fetchUser } from "@/lib/api"; // ❌ lint error

Armadilhas

Coisas que vão te morder. Cada armadilha inclui o que dá errado, por que acontece e a correção.

Falsos positivos do exhaustive-deps - Esta regra às vezes sinaliza referências estáveis como dispatch ou refs. Correção: Use // eslint-disable-next-line react-hooks/exhaustive-deps apenas quando tiver certeza de que a dependência é estável. Nunca a desative globalmente.
Conflitos do no-unused-vars com TypeScript - O no-unused-vars base do ESLint e o @typescript-eslint/no-unused-vars podem entrar em conflito. Correção: Desative a regra base e use apenas a versão do TypeScript: "no-unused-vars": "off".
import/order não auto-corrige - A regra relata violações, mas o --fix funciona apenas para reordenar, não para adicionar novas linhas entre grupos retroativamente. Correção: Execute eslint --fix e adicione manualmente linhas em branco na primeira passagem.
Severidade importa para CI - Usar "warn" significa que a CI passa mesmo com violações. Se você quiser impor uma regra, use "error". Correção: Reserve "warn" para regras para as quais você está migrando, use "error" para regras impostas.

Alternativas

Outras maneiras de resolver o mesmo problema - e quando cada uma é a melhor escolha.

Alternativa	Use Quando	Não Use Quando
Padrões do `next/core-web-vitals`	Você quer padrões sensatos sem personalização	Você precisa de regras mais rigorosas ou específicas do projeto
Regras de lint do Biome	Você quer linting mais rápido com regras integradas	Você precisa da amplitude total dos plugins ESLint
Compilador TypeScript (`tsc --noEmit`)	Você quer verificações em nível de tipo que o ESLint não pode fazer	Você precisa de aplicação de estilo de código ou padrões

FAQs

Qual a diferença entre os níveis de severidade "off", "warn" e "error"?

"off" (0) desabilita a regra completamente.
"warn" (1) mostra um aviso amarelo, mas não falha a CI ou bloqueia builds.
"error" (2) mostra um erro vermelho, falha a CI e bloqueia builds.

Por que devo usar @typescript-eslint/no-unused-vars em vez do no-unused-vars base?

O no-unused-vars base do ESLint não entende a sintaxe do TypeScript (interfaces, type aliases, enums).
As duas regras entram em conflito quando ambas estão habilitadas.
Desative a regra base e use apenas a versão do TypeScript:

"no-unused-vars": "off",
"@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],

O que consistent-type-imports impõe?

// Enforced (correct):
import type { User } from "@/types";
import { fetchUser } from "@/lib/api";
 
// Rejected (lint error):
import { User, fetchUser } from "@/lib/api";

Ele separa imports apenas de tipo de imports de valor para que os bundlers possam fazer tree-shake dos tipos.

Como a regra import/order organiza os imports?

Agrupa imports em categorias: builtin, external, internal, parent/sibling, index, type.
Impõe linhas em branco entre os grupos com "newlines-between": "always".
Ordena alfabeticamente os imports dentro de cada grupo.

Armadilha: Por que import/order não auto-corrige completamente na primeira execução?

eslint --fix pode reordenar imports dentro dos grupos.
Ele nem sempre adiciona linhas em branco ausentes entre os grupos retroativamente.
Execute eslint --fix uma vez, depois adicione manualmente linhas em branco na passagem inicial.

Quando devo usar "warn" versus "error" para uma regra?

Use "warn" para regras para as quais você está migrando ou que são consultivas.
Use "error" para regras que você deseja impor estritamente na CI.
Lembre-se: "warn" não falhará a CI, então as violações se acumulam silenciosamente se você esquecer de promover para "error".

O que react-hooks/exhaustive-deps detecta?

Dependências ausentes nos arrays de dependência de useEffect, useMemo e useCallback.
Adicionar todas as dependências evita bugs de closure obsoleto.
Definido como "warn" porque pode produzir falsos positivos com referências estáveis como dispatch.

Armadilha: Posso desativar exhaustive-deps globalmente com segurança?

Não. Desativá-lo globalmente oculta bugs reais onde os efeitos usam valores obsoletos.
Em vez disso, suprima-o por linha com // eslint-disable-next-line react-hooks/exhaustive-deps apenas quando tiver certeza de que a dependência é estável.

O que react/jsx-no-target-blank protege contra?

Links com target="_blank" sem rel="noreferrer" expõem sua página a ataques de window.opener.
A regra impõe a adição de rel="noreferrer" a todos os links externos.

Como passo opções para uma regra?

// Severity only:
"rule-name": "error"
 
// Severity with options:
"rule-name": ["error", { option: "value" }]

O segundo elemento do array é o objeto de opções da regra.

Quais regras específicas do TypeScript devo habilitar além dos padrões?

Regra	Propósito
`@typescript-eslint/no-explicit-any`	Sinaliza o uso de `any`
`@typescript-eslint/no-non-null-assertion`	Sinaliza asserções `!`
`@typescript-eslint/prefer-nullish-coalescing`	Prefere `??` em vez de `\|\|`
`@typescript-eslint/consistent-type-imports`	Impõe `import type`

Como sobrescrevo uma regra definida por next/core-web-vitals?

Adicione um objeto rules após o array extends na sua configuração flat.
Suas regras substituem os padrões do preset.

const eslintConfig = [
  ...compat.extends("next/core-web-vitals"),
  { rules: { "react/no-unescaped-entities": "off" } },
];

Relacionado

Configuração do ESLint para Next.js - configuração inicial do ESLint
Plugins do ESLint - instalar e configurar plugins
Modo Estrito do TypeScript - complementar o ESLint com opções de compilador estritas
Integração ESLint + Prettier - evitar conflitos de formatação

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// Severity levels
"off"   // 0 - disable the rule
"warn"  // 1 - yellow warning, does not fail CI
"error" // 2 - red error, fails CI and blocks builds
 
// Common pattern: override a rule
{
  rules: {
    "rule-name": "error",
    "rule-name": ["error", { option: "value" }],
  },
}

Quando usar isso: Quando os presets padrão são muito permissivos ou muito rigorosos e você precisa ajustar regras específicas.

Exemplo de Trabalho

// eslint.config.mjs
import { FlatCompat } from "@eslint/eslintrc";
import { dirname } from "path";
import { fileURLToPath } from "url";
 
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
 
const compat = new FlatCompat({ baseDirectory: __dirname });
 
const eslintConfig = [
  ...compat.extends("next/core-web-vitals", "next/typescript"),
  {
    rules: {
      // --- React rules ---
      "react/jsx-no-target-blank": "error",
      "react/no-unescaped-entities": "off",
      "react/self-closing-comp": "warn",
      "react/jsx-curly-brace-presence": [
        "warn",
        { props: "never", children: "never" },
      ],
 
      // --- Hooks rules ---
      "react-hooks/rules-of-hooks": "error",
      "react-hooks/exhaustive-deps": "warn",
 
      // --- TypeScript rules ---
      "@typescript-eslint/no-unused-vars": [
        "error",
        {
          argsIgnorePattern: "^_",
          varsIgnorePattern: "^_",
          caughtErrorsIgnorePattern: "^_",
        },
      ],
      "@typescript-eslint/no-explicit-any": "warn",
      "@typescript-eslint/consistent-type-imports": [
        "error",
        { prefer: "type-imports" },
      ],
 
      // --- Import rules ---
      "import/order": [
        "warn",
        {
          groups: [
            "builtin",
            "external",
            "internal",
            ["parent", "sibling"],
            "index",
            "type",
          ],
          "newlines-between": "always",
          alphabetize: { order: "asc", caseInsensitive: true },
        },
      ],
      "import/no-duplicates": "error",
 
      // --- Accessibility rules ---
      "jsx-a11y/alt-text": "error",
      "jsx-a11y/anchor-is-valid": "warn",
    },
  },
];
 
export default eslintConfig;

O que isso demonstra:

Regras organizadas por categoria: React, hooks, TypeScript, imports, acessibilidade
Mistura de severidades error (precisa corrigir) e warn (deve corrigir)
Ignorando variáveis não utilizadas prefixadas com _ com base em padrão
Ordenação de imports com separação de grupos e ordenação alfabética

Mergulho Profundo

Como Funciona

Cada regra tem um nível de severidade: "off", "warn", ou "error"
Regras podem aceitar opções como segundo elemento de um array: ["error", { option: true }]
O preset next/core-web-vitals já habilita muitas regras - você as sobrescreve na sua própria configuração
Regras de plugins são prefixadas com o nome do plugin (ex: react/, @typescript-eslint/)

Variações

Regras do React que valem a pena conhecer:

Regra	O que Detecta
`react/jsx-no-target-blank`	Falta de `rel="noreferrer"` em links com `target="_blank"`
`react/no-unescaped-entities`	`'` ou `"` não escapados em texto JSX
`react/self-closing-comp`	`<div></div>` em vez de `<div />` para elementos vazios
`react/jsx-curly-brace-presence`	`{"string"}` desnecessário em vez de `string` no JSX
`react/no-array-index-key`	Uso do índice do array como `key` prop

Regras de Hooks:

Regra	O que Detecta
`react-hooks/rules-of-hooks`	Hooks chamados condicionalmente ou em loops
`react-hooks/exhaustive-deps`	Dependências ausentes em useEffect, useMemo, useCallback

Regras do TypeScript que valem a pena habilitar:

Regra	O que Detecta
`@typescript-eslint/no-unused-vars`	Variáveis declaradas mas não utilizadas
`@typescript-eslint/no-explicit-any`	Uso do tipo `any`
`@typescript-eslint/consistent-type-imports`	Falta da palavra-chave `type` em imports apenas de tipo
`@typescript-eslint/no-non-null-assertion`	Uso da asserção não nula `!`
`@typescript-eslint/prefer-nullish-coalescing`	Uso do OR lógico em vez de `??`

Notas do TypeScript

// consistent-type-imports enforces this:
import type { User } from "@/types"; // type-only import
import { fetchUser } from "@/lib/api"; // value import
 
// Instead of mixing them:
import { User, fetchUser } from "@/lib/api"; // ❌ lint error

Armadilhas

Coisas que vão te morder. Cada armadilha inclui o que dá errado, por que acontece e a correção.

Falsos positivos do exhaustive-deps - Esta regra às vezes sinaliza referências estáveis como dispatch ou refs. Correção: Use // eslint-disable-next-line react-hooks/exhaustive-deps apenas quando tiver certeza de que a dependência é estável. Nunca a desative globalmente.
Conflitos do no-unused-vars com TypeScript - O no-unused-vars base do ESLint e o @typescript-eslint/no-unused-vars podem entrar em conflito. Correção: Desative a regra base e use apenas a versão do TypeScript: "no-unused-vars": "off".
import/order não auto-corrige - A regra relata violações, mas o --fix funciona apenas para reordenar, não para adicionar novas linhas entre grupos retroativamente. Correção: Execute eslint --fix e adicione manualmente linhas em branco na primeira passagem.
Severidade importa para CI - Usar "warn" significa que a CI passa mesmo com violações. Se você quiser impor uma regra, use "error". Correção: Reserve "warn" para regras para as quais você está migrando, use "error" para regras impostas.

Alternativas

Outras maneiras de resolver o mesmo problema - e quando cada uma é a melhor escolha.

Alternativa	Use Quando	Não Use Quando
Padrões do `next/core-web-vitals`	Você quer padrões sensatos sem personalização	Você precisa de regras mais rigorosas ou específicas do projeto
Regras de lint do Biome	Você quer linting mais rápido com regras integradas	Você precisa da amplitude total dos plugins ESLint
Compilador TypeScript (`tsc --noEmit`)	Você quer verificações em nível de tipo que o ESLint não pode fazer	Você precisa de aplicação de estilo de código ou padrões

FAQs

Qual a diferença entre os níveis de severidade "off", "warn" e "error"?

"off" (0) desabilita a regra completamente.
"warn" (1) mostra um aviso amarelo, mas não falha a CI ou bloqueia builds.
"error" (2) mostra um erro vermelho, falha a CI e bloqueia builds.

Por que devo usar @typescript-eslint/no-unused-vars em vez do no-unused-vars base?

O no-unused-vars base do ESLint não entende a sintaxe do TypeScript (interfaces, type aliases, enums).
As duas regras entram em conflito quando ambas estão habilitadas.
Desative a regra base e use apenas a versão do TypeScript:

"no-unused-vars": "off",
"@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],

O que consistent-type-imports impõe?

// Enforced (correct):
import type { User } from "@/types";
import { fetchUser } from "@/lib/api";
 
// Rejected (lint error):
import { User, fetchUser } from "@/lib/api";

Ele separa imports apenas de tipo de imports de valor para que os bundlers possam fazer tree-shake dos tipos.

Como a regra import/order organiza os imports?

Agrupa imports em categorias: builtin, external, internal, parent/sibling, index, type.
Impõe linhas em branco entre os grupos com "newlines-between": "always".
Ordena alfabeticamente os imports dentro de cada grupo.

Armadilha: Por que import/order não auto-corrige completamente na primeira execução?

eslint --fix pode reordenar imports dentro dos grupos.
Ele nem sempre adiciona linhas em branco ausentes entre os grupos retroativamente.
Execute eslint --fix uma vez, depois adicione manualmente linhas em branco na passagem inicial.

Quando devo usar "warn" versus "error" para uma regra?

Use "warn" para regras para as quais você está migrando ou que são consultivas.
Use "error" para regras que você deseja impor estritamente na CI.
Lembre-se: "warn" não falhará a CI, então as violações se acumulam silenciosamente se você esquecer de promover para "error".

O que react-hooks/exhaustive-deps detecta?

Dependências ausentes nos arrays de dependência de useEffect, useMemo e useCallback.
Adicionar todas as dependências evita bugs de closure obsoleto.
Definido como "warn" porque pode produzir falsos positivos com referências estáveis como dispatch.

Armadilha: Posso desativar exhaustive-deps globalmente com segurança?

Não. Desativá-lo globalmente oculta bugs reais onde os efeitos usam valores obsoletos.
Em vez disso, suprima-o por linha com // eslint-disable-next-line react-hooks/exhaustive-deps apenas quando tiver certeza de que a dependência é estável.

O que react/jsx-no-target-blank protege contra?

Links com target="_blank" sem rel="noreferrer" expõem sua página a ataques de window.opener.
A regra impõe a adição de rel="noreferrer" a todos os links externos.

Como passo opções para uma regra?

// Severity only:
"rule-name": "error"
 
// Severity with options:
"rule-name": ["error", { option: "value" }]

O segundo elemento do array é o objeto de opções da regra.

Quais regras específicas do TypeScript devo habilitar além dos padrões?

Regra	Propósito
`@typescript-eslint/no-explicit-any`	Sinaliza o uso de `any`
`@typescript-eslint/no-non-null-assertion`	Sinaliza asserções `!`
`@typescript-eslint/prefer-nullish-coalescing`	Prefere `??` em vez de `\|\|`
`@typescript-eslint/consistent-type-imports`	Impõe `import type`

Como sobrescrevo uma regra definida por next/core-web-vitals?

Adicione um objeto rules após o array extends na sua configuração flat.
Suas regras substituem os padrões do preset.

const eslintConfig = [
  ...compat.extends("next/core-web-vitals"),
  { rules: { "react/no-unescaped-entities": "off" } },
];

Relacionado

Configuração do ESLint para Next.js - configuração inicial do ESLint
Plugins do ESLint - instalar e configurar plugins
Modo Estrito do TypeScript - complementar o ESLint com opções de compilador estritas
Integração ESLint + Prettier - evitar conflitos de formatação

Regras Essenciais do ESLint

Buscar na documentação

Regras Essenciais do ESLint