Plugins ESLint

Q: Quais plugins já estão incluídos em next/core-web-vitals?

eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-next eslint-plugin-import eslint-plugin-jsx-a11y Você não precisa instalá-los separadamente.

Q: Como eu escopo um plugin para tipos de arquivo específicos?

Use a propriedade files para restringir regras a globs correspondentes.

Q: O que o eslint-plugin-tailwindcss fornece?

tailwindcss/classnames-order ordena as classes Tailwind na ordem recomendada. tailwindcss/no-contradicting-classname detecta conflitos como p-4 p-8. tailwindcss/no-custom-classname sinaliza classes que não estão na configuração Tailwind (frequentemente desativado).

Q: Como o plugin Tailwind encontra meu arquivo tailwind.config?

Ele procura por tailwind.config.* na raiz do projeto por padrão. Se sua configuração estiver em um local não padrão, defina a opção config nas configurações do plugin. Sem o caminho de configuração correto, o plugin falha silenciosamente.

Q: Qual é a diferença entre plugins nativos de configuração flat e plugins FlatCompat?

Plugins nativos de configuração flat exportam configs["flat/recommended"] diretamente. Plugins mais antigos precisam de encapsulamento FlatCompat para funcionar com a configuração flat do ESLint 9. Verifique o README de cada plugin para o status de suporte à configuração flat.

Q: Como adiciono regras específicas de TypeScript via @typescript-eslint?

Estes são incluídos via next/typescript, mas você pode sobrescrever a severidade deles.

Q: Como verifico qual plugin fornece uma regra específica?

As regras são prefixadas com o namespace do plugin: react/, @typescript-eslint/, jsx-a11y/, etc. Execute npx eslint --print-config src/app/page.tsx para ver todas as regras ativas e suas fontes.

Instale e configure plugins ESLint para React, TypeScript, acessibilidade, Tailwind CSS e testes.

Receita

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

# Plugins principais (a maioria incluída com next/core-web-vitals)
npm install --save-dev eslint-plugin-react eslint-plugin-react-hooks
 
# TypeScript
npm install --save-dev @typescript-eslint/eslint-plugin @typescript-eslint/parser
 
# Imports
npm install --save-dev eslint-plugin-import
 
# Acessibilidade
npm install --save-dev eslint-plugin-jsx-a11y
 
# Tailwind CSS
npm install --save-dev eslint-plugin-tailwindcss
 
# Testing Library
npm install --save-dev eslint-plugin-testing-library

Quando usar isso: Quando você precisar de regras além do que next/core-web-vitals oferece - ordenação de classes Tailwind, melhores práticas de teste ou verificações de acessibilidade mais rigorosas.

Exemplo Funcional

// eslint.config.mjs
import { FlatCompat } from "@eslint/eslintrc";
import tailwindcss from "eslint-plugin-tailwindcss";
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 = [
  // Presets do Next.js (inclui react, react-hooks, import, jsx-a11y)
  ...compat.extends("next/core-web-vitals", "next/typescript"),
 
  // Plugin Tailwind CSS (suporte nativo para configuração flat)
  ...tailwindcss.configs["flat/recommended"],
 
  // Testing Library (apenas para arquivos de teste)
  {
    files: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
    ...compat.extends("plugin:testing-library/react")[0],
  },
 
  // Sobrescritas de regras personalizadas
  {
    rules: {
      // Tailwind
      "tailwindcss/classnames-order": "warn",
      "tailwindcss/no-custom-classname": "off",
 
      // Acessibilidade
      "jsx-a11y/anchor-is-valid": "warn",
      "jsx-a11y/alt-text": "error",
 
      // TypeScript
      "@typescript-eslint/no-unused-vars": [
        "error",
        { argsIgnorePattern: "^_" },
      ],
      "@typescript-eslint/consistent-type-imports": "error",
 
      // Imports
      "import/order": [
        "warn",
        {
          groups: [
            "builtin",
            "external",
            "internal",
            ["parent", "sibling"],
            "index",
            "type",
          ],
          "newlines-between": "always",
          alphabetize: { order: "asc" },
        },
      ],
    },
  },
];
 
export default eslintConfig;

O que isso demonstra:

Camadas de plugins sobre os presets do Next.js
Plugin Tailwind usando seu suporte nativo de configuração flat
Escopo do plugin testing-library apenas para arquivos de teste
Ordenação de imports com separação de grupos

Mergulho Profundo

Como Funciona

Plugins fornecem coleções de regras sob um namespace (por exemplo, react/, jsx-a11y/)
next/core-web-vitals já inclui eslint-plugin-react, eslint-plugin-react-hooks, eslint-plugin-next, eslint-plugin-import e eslint-plugin-jsx-a11y
Plugins adicionais como tailwindcss e testing-library são adicionados por cima
Na configuração flat, alguns plugins exportam configs["flat/recommended"] diretamente; outros precisam de FlatCompat

Variações

Visão geral dos plugins:

Plugin	Namespace	O que faz
`eslint-plugin-react`	`react/`	Melhores práticas de JSX, padrões de componentes
`eslint-plugin-react-hooks`	`react-hooks/`	Regras de Hooks e verificação de dependências
`@typescript-eslint/eslint-plugin`	`@typescript-eslint/`	Regras específicas de TypeScript
`eslint-plugin-import`	`import/`	Ordenação de imports, sem duplicatas, sem não resolvidos
`eslint-plugin-jsx-a11y`	`jsx-a11y/`	Regras de acessibilidade para elementos JSX
`eslint-plugin-tailwindcss`	`tailwindcss/`	Ordenação de classes, sem classes contraditórias
`eslint-plugin-testing-library`	`testing-library/`	Melhores práticas para Testing Library

Regras chave do plugin Tailwind:

{
  rules: {
    "tailwindcss/classnames-order": "warn",        // Ordena classes
    "tailwindcss/no-custom-classname": "off",       // Permite classes personalizadas
    "tailwindcss/no-contradicting-classname": "error", // Captura p-4 p-8
    "tailwindcss/enforces-negative-arbitrary-values": "warn",
  },
}

Plugin Testing Library (com escopo para arquivos de teste):

{
  files: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
  rules: {
    "testing-library/await-async-queries": "error",
    "testing-library/no-debugging-utils": "warn",
    "testing-library/no-dom-import": "error",
    "testing-library/prefer-screen-queries": "warn",
  },
}

Notas sobre TypeScript

// Regras chave do @typescript-eslint:
// no-unused-vars - detecta imports e variáveis não utilizados
// no-explicit-any - sinaliza o uso do tipo `any`
// consistent-type-imports - impõe a sintaxe `import type { X }`
// no-non-null-assertion - sinaliza asserções `obj!.prop`
// prefer-nullish-coalescing - sinaliza `||` onde `??` é mais seguro
 
// Estes complementam o modo estrito do tsconfig, mas detectam
// coisas diferentes (padrões vs tipos)

Armadilhas

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

Registro duplicado de plugin - Instalar eslint-plugin-react manualmente quando next/core-web-vitals já o inclui causa conflitos. Correção: Verifique o que o preset inclui antes de adicionar plugins. Adicione apenas plugins que não estejam já incluídos.
Plugin Tailwind requer configuração - eslint-plugin-tailwindcss precisa encontrar seu arquivo tailwind.config.*. Se sua configuração estiver em um local não padrão, o plugin falha silenciosamente. Correção: Defina a opção config nas configurações do plugin.
Plugin de teste em todos os arquivos - Aplicar regras do testing-library globalmente sinaliza código não relacionado a testes. Correção: Sempre escopoe com files: ["**/*.test.*"].
Compatibilidade com configuração flat - Nem todos os plugins suportam configuração flat nativamente. Alguns precisam de encapsulamento FlatCompat, o que pode causar comportamento inesperado. Correção: Verifique o README do plugin para suporte à configuração flat e use FlatCompat apenas quando necessário.
Desempenho com muitos plugins - Cada plugin adiciona tempo de análise e verificação de regras. Cinco ou mais plugins podem diminuir notavelmente a velocidade do linting. Correção: Use TIMING=1 npx eslint . para perfilar quais regras são lentas e desabilite qualquer uma que você não precise.

Alternativas

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

Alternativa	Use Quando	Não Use Quando
Biome	Você quer linting + formatação em uma única ferramenta rápida	Você precisa de regras Tailwind ou de teste
Apenas `next/core-web-vitals`	Os plugins incluídos são suficientes para seu projeto	Você precisa de ordenação de classes Tailwind ou regras de teste
`oxlint`	Você quer linting ultrarrápido com regras comuns	Você precisa de regras específicas de plugins (Tailwind, teste)

FAQs

Quais plugins já estão incluídos em next/core-web-vitals?

eslint-plugin-react
eslint-plugin-react-hooks
eslint-plugin-next
eslint-plugin-import
eslint-plugin-jsx-a11y

Você não precisa instalá-los separadamente.

Armadilha: O que acontece se eu instalar um plugin que next/core-web-vitals já inclui?

Você obtém registro duplicado de plugin, o que causa conflitos e comportamento inesperado das regras.
Verifique o que o preset inclui antes de adicionar plugins manualmente.
Adicione apenas plugins que não estejam já incluídos pelo preset.

Como eu escopo um plugin para tipos de arquivo específicos?

{
  files: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
  rules: {
    "testing-library/await-async-queries": "error",
    "testing-library/prefer-screen-queries": "warn",
  },
}

Use a propriedade files para restringir regras a globs correspondentes.

O que o eslint-plugin-tailwindcss fornece?

tailwindcss/classnames-order ordena as classes Tailwind na ordem recomendada.
tailwindcss/no-contradicting-classname detecta conflitos como p-4 p-8.
tailwindcss/no-custom-classname sinaliza classes que não estão na configuração Tailwind (frequentemente desativado).

Como o plugin Tailwind encontra meu arquivo tailwind.config?

Ele procura por tailwind.config.* na raiz do projeto por padrão.
Se sua configuração estiver em um local não padrão, defina a opção config nas configurações do plugin.
Sem o caminho de configuração correto, o plugin falha silenciosamente.

Qual é a diferença entre plugins nativos de configuração flat e plugins FlatCompat?

Plugins nativos de configuração flat exportam configs["flat/recommended"] diretamente.
Plugins mais antigos precisam de encapsulamento FlatCompat para funcionar com a configuração flat do ESLint 9.
Verifique o README de cada plugin para o status de suporte à configuração flat.

Armadilha: Por que adicionar muitos plugins lentifica o linting?

Cada plugin adiciona sua própria sobrecarga de análise e verificação de regras.
Cinco ou mais plugins ativos podem diminuir notavelmente a velocidade do linting.
Perfilar com TIMING=1 npx eslint . para encontrar as regras mais lentas e desabilitar aquelas que você não precisa.

Como adiciono regras específicas de TypeScript via @typescript-eslint?

"@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
"@typescript-eslint/consistent-type-imports": "error",
"@typescript-eslint/no-explicit-any": "warn",

Estes são incluídos via next/typescript, mas você pode sobrescrever a severidade deles.

Posso usar eslint-plugin-testing-library em todos os arquivos?

Não. Aplicá-lo globalmente sinaliza código não relacionado a testes com falsos positivos.
Sempre escopoe com files: ["**/*.test.*", "**/*.spec.*"].

Como verifico qual plugin fornece uma regra específica?

As regras são prefixadas com o namespace do plugin: react/, @typescript-eslint/, jsx-a11y/, etc.
Execute npx eslint --print-config src/app/page.tsx para ver todas as regras ativas e suas fontes.

Quais regras de acessibilidade o jsx-a11y fornece?

jsx-a11y/alt-text requer atributos alt em imagens.
jsx-a11y/anchor-is-valid avisa sobre âncoras sem href válido.
O plugin verifica papéis ARIA, acessibilidade por teclado e rótulos de formulário.

Devo usar regras do TypeScript ESLint ou opções estritas do tsconfig?

Use ambos. Eles detectam coisas diferentes.
@typescript-eslint detecta padrões de código (variáveis não usadas, promises flutuantes, any explícito).
Opções estritas do tsconfig detectam problemas em nível de tipo (verificações de nulo, any implícito, acesso a índice não verificado).

Relacionados

Configuração ESLint para Next.js - configuração base do ESLint
Regras Essenciais do ESLint - configure regras individuais
Integração ESLint + Prettier - evite conflitos de formatação
Husky & lint-staged - execute plugins apenas em arquivos alterados

Receita

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

# Plugins principais (a maioria incluída com next/core-web-vitals)
npm install --save-dev eslint-plugin-react eslint-plugin-react-hooks
 
# TypeScript
npm install --save-dev @typescript-eslint/eslint-plugin @typescript-eslint/parser
 
# Imports
npm install --save-dev eslint-plugin-import
 
# Acessibilidade
npm install --save-dev eslint-plugin-jsx-a11y
 
# Tailwind CSS
npm install --save-dev eslint-plugin-tailwindcss
 
# Testing Library
npm install --save-dev eslint-plugin-testing-library

Exemplo Funcional

// eslint.config.mjs
import { FlatCompat } from "@eslint/eslintrc";
import tailwindcss from "eslint-plugin-tailwindcss";
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 = [
  // Presets do Next.js (inclui react, react-hooks, import, jsx-a11y)
  ...compat.extends("next/core-web-vitals", "next/typescript"),
 
  // Plugin Tailwind CSS (suporte nativo para configuração flat)
  ...tailwindcss.configs["flat/recommended"],
 
  // Testing Library (apenas para arquivos de teste)
  {
    files: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
    ...compat.extends("plugin:testing-library/react")[0],
  },
 
  // Sobrescritas de regras personalizadas
  {
    rules: {
      // Tailwind
      "tailwindcss/classnames-order": "warn",
      "tailwindcss/no-custom-classname": "off",
 
      // Acessibilidade
      "jsx-a11y/anchor-is-valid": "warn",
      "jsx-a11y/alt-text": "error",
 
      // TypeScript
      "@typescript-eslint/no-unused-vars": [
        "error",
        { argsIgnorePattern: "^_" },
      ],
      "@typescript-eslint/consistent-type-imports": "error",
 
      // Imports
      "import/order": [
        "warn",
        {
          groups: [
            "builtin",
            "external",
            "internal",
            ["parent", "sibling"],
            "index",
            "type",
          ],
          "newlines-between": "always",
          alphabetize: { order: "asc" },
        },
      ],
    },
  },
];
 
export default eslintConfig;

O que isso demonstra:

Camadas de plugins sobre os presets do Next.js
Plugin Tailwind usando seu suporte nativo de configuração flat
Escopo do plugin testing-library apenas para arquivos de teste
Ordenação de imports com separação de grupos

Mergulho Profundo

Como Funciona

Plugins fornecem coleções de regras sob um namespace (por exemplo, react/, jsx-a11y/)
next/core-web-vitals já inclui eslint-plugin-react, eslint-plugin-react-hooks, eslint-plugin-next, eslint-plugin-import e eslint-plugin-jsx-a11y
Plugins adicionais como tailwindcss e testing-library são adicionados por cima
Na configuração flat, alguns plugins exportam configs["flat/recommended"] diretamente; outros precisam de FlatCompat

Variações

Visão geral dos plugins:

Plugin	Namespace	O que faz
`eslint-plugin-react`	`react/`	Melhores práticas de JSX, padrões de componentes
`eslint-plugin-react-hooks`	`react-hooks/`	Regras de Hooks e verificação de dependências
`@typescript-eslint/eslint-plugin`	`@typescript-eslint/`	Regras específicas de TypeScript
`eslint-plugin-import`	`import/`	Ordenação de imports, sem duplicatas, sem não resolvidos
`eslint-plugin-jsx-a11y`	`jsx-a11y/`	Regras de acessibilidade para elementos JSX
`eslint-plugin-tailwindcss`	`tailwindcss/`	Ordenação de classes, sem classes contraditórias
`eslint-plugin-testing-library`	`testing-library/`	Melhores práticas para Testing Library

Regras chave do plugin Tailwind:

{
  rules: {
    "tailwindcss/classnames-order": "warn",        // Ordena classes
    "tailwindcss/no-custom-classname": "off",       // Permite classes personalizadas
    "tailwindcss/no-contradicting-classname": "error", // Captura p-4 p-8
    "tailwindcss/enforces-negative-arbitrary-values": "warn",
  },
}

Plugin Testing Library (com escopo para arquivos de teste):

{
  files: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
  rules: {
    "testing-library/await-async-queries": "error",
    "testing-library/no-debugging-utils": "warn",
    "testing-library/no-dom-import": "error",
    "testing-library/prefer-screen-queries": "warn",
  },
}

Notas sobre TypeScript

// Regras chave do @typescript-eslint:
// no-unused-vars - detecta imports e variáveis não utilizados
// no-explicit-any - sinaliza o uso do tipo `any`
// consistent-type-imports - impõe a sintaxe `import type { X }`
// no-non-null-assertion - sinaliza asserções `obj!.prop`
// prefer-nullish-coalescing - sinaliza `||` onde `??` é mais seguro
 
// Estes complementam o modo estrito do tsconfig, mas detectam
// coisas diferentes (padrões vs tipos)

Armadilhas

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

Registro duplicado de plugin - Instalar eslint-plugin-react manualmente quando next/core-web-vitals já o inclui causa conflitos. Correção: Verifique o que o preset inclui antes de adicionar plugins. Adicione apenas plugins que não estejam já incluídos.
Plugin Tailwind requer configuração - eslint-plugin-tailwindcss precisa encontrar seu arquivo tailwind.config.*. Se sua configuração estiver em um local não padrão, o plugin falha silenciosamente. Correção: Defina a opção config nas configurações do plugin.
Plugin de teste em todos os arquivos - Aplicar regras do testing-library globalmente sinaliza código não relacionado a testes. Correção: Sempre escopoe com files: ["**/*.test.*"].
Compatibilidade com configuração flat - Nem todos os plugins suportam configuração flat nativamente. Alguns precisam de encapsulamento FlatCompat, o que pode causar comportamento inesperado. Correção: Verifique o README do plugin para suporte à configuração flat e use FlatCompat apenas quando necessário.
Desempenho com muitos plugins - Cada plugin adiciona tempo de análise e verificação de regras. Cinco ou mais plugins podem diminuir notavelmente a velocidade do linting. Correção: Use TIMING=1 npx eslint . para perfilar quais regras são lentas e desabilite qualquer uma que você não precise.

Alternativas

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

Alternativa	Use Quando	Não Use Quando
Biome	Você quer linting + formatação em uma única ferramenta rápida	Você precisa de regras Tailwind ou de teste
Apenas `next/core-web-vitals`	Os plugins incluídos são suficientes para seu projeto	Você precisa de ordenação de classes Tailwind ou regras de teste
`oxlint`	Você quer linting ultrarrápido com regras comuns	Você precisa de regras específicas de plugins (Tailwind, teste)

FAQs

Quais plugins já estão incluídos em next/core-web-vitals?

eslint-plugin-react
eslint-plugin-react-hooks
eslint-plugin-next
eslint-plugin-import
eslint-plugin-jsx-a11y

Você não precisa instalá-los separadamente.

Armadilha: O que acontece se eu instalar um plugin que next/core-web-vitals já inclui?

Você obtém registro duplicado de plugin, o que causa conflitos e comportamento inesperado das regras.
Verifique o que o preset inclui antes de adicionar plugins manualmente.
Adicione apenas plugins que não estejam já incluídos pelo preset.

Como eu escopo um plugin para tipos de arquivo específicos?

{
  files: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
  rules: {
    "testing-library/await-async-queries": "error",
    "testing-library/prefer-screen-queries": "warn",
  },
}

Use a propriedade files para restringir regras a globs correspondentes.

O que o eslint-plugin-tailwindcss fornece?

tailwindcss/classnames-order ordena as classes Tailwind na ordem recomendada.
tailwindcss/no-contradicting-classname detecta conflitos como p-4 p-8.
tailwindcss/no-custom-classname sinaliza classes que não estão na configuração Tailwind (frequentemente desativado).

Como o plugin Tailwind encontra meu arquivo tailwind.config?

Ele procura por tailwind.config.* na raiz do projeto por padrão.
Se sua configuração estiver em um local não padrão, defina a opção config nas configurações do plugin.
Sem o caminho de configuração correto, o plugin falha silenciosamente.

Qual é a diferença entre plugins nativos de configuração flat e plugins FlatCompat?

Plugins nativos de configuração flat exportam configs["flat/recommended"] diretamente.
Plugins mais antigos precisam de encapsulamento FlatCompat para funcionar com a configuração flat do ESLint 9.
Verifique o README de cada plugin para o status de suporte à configuração flat.

Armadilha: Por que adicionar muitos plugins lentifica o linting?

Cada plugin adiciona sua própria sobrecarga de análise e verificação de regras.
Cinco ou mais plugins ativos podem diminuir notavelmente a velocidade do linting.
Perfilar com TIMING=1 npx eslint . para encontrar as regras mais lentas e desabilitar aquelas que você não precisa.

Como adiciono regras específicas de TypeScript via @typescript-eslint?

"@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
"@typescript-eslint/consistent-type-imports": "error",
"@typescript-eslint/no-explicit-any": "warn",

Estes são incluídos via next/typescript, mas você pode sobrescrever a severidade deles.

Posso usar eslint-plugin-testing-library em todos os arquivos?

Não. Aplicá-lo globalmente sinaliza código não relacionado a testes com falsos positivos.
Sempre escopoe com files: ["**/*.test.*", "**/*.spec.*"].

Como verifico qual plugin fornece uma regra específica?

As regras são prefixadas com o namespace do plugin: react/, @typescript-eslint/, jsx-a11y/, etc.
Execute npx eslint --print-config src/app/page.tsx para ver todas as regras ativas e suas fontes.

Quais regras de acessibilidade o jsx-a11y fornece?

jsx-a11y/alt-text requer atributos alt em imagens.
jsx-a11y/anchor-is-valid avisa sobre âncoras sem href válido.
O plugin verifica papéis ARIA, acessibilidade por teclado e rótulos de formulário.

Devo usar regras do TypeScript ESLint ou opções estritas do tsconfig?

Use ambos. Eles detectam coisas diferentes.
@typescript-eslint detecta padrões de código (variáveis não usadas, promises flutuantes, any explícito).
Opções estritas do tsconfig detectam problemas em nível de tipo (verificações de nulo, any implícito, acesso a índice não verificado).

Relacionados

Configuração ESLint para Next.js - configuração base do ESLint
Regras Essenciais do ESLint - configure regras individuais
Integração ESLint + Prettier - evite conflitos de formatação
Husky & lint-staged - execute plugins apenas em arquivos alterados

Plugins ESLint

Buscar na documentação

Plugins ESLint