Configuração do ESLint para Next.js

Q: Por que o Next.js usa FlatCompat em vez de configuração plana nativa?

As predefinições ESLint do Next.js (next/core-web-vitals, next/typescript) ainda usam o formato extends legado internamente. FlatCompat une essas configurações legadas à configuração plana do ESLint 9. Assim que o Next.js lançar suporte nativo para configuração plana, FlatCompat não será mais necessário.

Q: Qual é a diferença entre next/core-web-vitals e next/typescript?

next/core-web-vitals agrupa regras de React, hooks, importação e específicas do Next.js com padrões rigorosos. next/typescript adiciona regras do @typescript-eslint/eslint-plugin ajustadas para Next.js. A maioria dos projetos estende ambos.

Q: Posso usar um arquivo .eslintrc em vez de eslint.config.mjs?

O ESLint 9 prefere configuração plana (eslint.config.mjs). Se existirem tanto um .eslintrc. quanto eslint.config.mjs, o ESLint voltará para o arquivo legado. Exclua todos os arquivos .eslintrc. ao migrar para configuração plana para evitar confusão.

Q: Armadilha: Por que o ESLint ignora meu padrão de ignores globais?

Na configuração plana, ignores só funciona como um ignore global quando é a única chave em seu objeto de configuração. Se você misturar ignores com rules no mesmo objeto, ele age como um filtro de arquivo, não um ignore global. Sempre coloque ignores globais em um objeto { ignores: [...] } separado.

Q: Como suprimo erros de variável não utilizada para parâmetros de função em TypeScript?

Prefira parâmetros não utilizados com _ e eles serão ignorados.

Q: Qual é o propósito da configuração __filename e __dirname em eslint.config.mjs?

Módulos ES não têm globais __filename ou __dirname. fileURLToPath(import.meta.url) e dirname() os recriam. FlatCompat requer baseDirectory para resolver caminhos de configuração relativos.

Q: Como faço a verificação de tipo do próprio arquivo de configuração ESLint?

eslint.config.mjs é JavaScript puro, não TypeScript. Você pode adicionar // @ts-check no topo e usar anotações JSDoc para verificação básica de tipo. Alternativamente, use eslint.config.ts com suporte experimental de configuração TypeScript no ESLint 9.

Q: Posso executar o ESLint diretamente em vez de usar next lint?

Use npx eslint . quando precisar de controle total sobre quais arquivos são verificados.

Configure o ESLint com o formato de configuração plana para um projeto Next.js usando predefinições integradas.

Receita

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

# Instale o ESLint (incluído com create-next-app)
npm install --save-dev eslint eslint-config-next
 
# Execute o linting via CLI do Next.js
npx next lint
 
# Execute o linting e corrija automaticamente
npx next lint --fix
 
# Execute o linting em diretórios específicos
npx next lint --dir src --dir app

Quando usar isso: Todo projeto Next.js deve ter o ESLint configurado desde o primeiro dia.

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: {
      // Personalize as regras aqui
      "@typescript-eslint/no-unused-vars": [
        "error",
        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
      ],
      "react/no-unescaped-entities": "off",
    },
  },
  {
    ignores: [
      "node_modules/",
      ".next/",
      "out/",
      "public/",
      "coverage/",
    ],
  },
];
 
export default eslintConfig;

O que isso demonstra:

Formato de configuração plana do ESLint 9 usando eslint.config.mjs
Uso do FlatCompat para unir configurações do Next.js (que ainda usam o formato legado) à configuração plana
Extensão de next/core-web-vitals (inclui regras de React, hooks e importação) e next/typescript
Personalização de uma regra e ignorar diretórios

Análise Detalhada

Como Funciona

O Next.js vem com sua própria integração ESLint via npx next lint
A predefinição next/core-web-vitals agrupa eslint-plugin-react, eslint-plugin-react-hooks, eslint-plugin-next e eslint-plugin-import com padrões rigorosos
A predefinição next/typescript adiciona regras do @typescript-eslint/eslint-plugin ajustadas para Next.js
O ESLint 9 usa configuração plana (eslint.config.mjs) em vez do formato legado .eslintrc
FlatCompat é uma ponte que permite usar configurações no estilo extends legado dentro da configuração plana - necessário porque as predefinições do Next.js ainda não foram totalmente migradas

Variações

ESLint Autônomo (sem next lint):

# Execute o ESLint diretamente
npx eslint . --fix
 
# Ou via script package.json

{
  "scripts": {
    "lint": "next lint",
    "lint:fix": "next lint --fix",
    "lint:strict": "next lint --strict"
  }
}

Modo Estrito (trata avisos como erros):

npx next lint --strict

Ignorando arquivos:

// Em eslint.config.mjs - bloco de ignores
{
  ignores: [
    "**/*.config.js",
    "**/*.config.mjs",
    "migrations/",
    "generated/",
  ],
}

Notas sobre TypeScript

# A predefinição next/typescript cuida disso automaticamente:
# - @typescript-eslint/parser é configurado
# - Regras cientes de TypeScript são habilitadas
# - Arquivos .ts e .tsx são incluídos por padrão

Armadilhas

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

Configuração plana não detectada - Se o ESLint ignorar seu eslint.config.mjs, você pode ter um arquivo .eslintrc.* sobrando. O ESLint 9 prefere configuração plana, mas volta para o legado se ambos existirem. Correção: Exclua todos os arquivos .eslintrc.* ao usar configuração plana.
Primeira execução solicita configuração - Executar npx next lint pela primeira vez exibe um assistente de configuração. Correção: Escolha "Strict" para next/core-web-vitals ou crie o arquivo de configuração manualmente com antecedência.
Ignores devem ser um objeto separado - Na configuração plana, o array ignores só funciona como um ignore global quando é a única chave em seu objeto de configuração. Misturar ignores com rules no mesmo objeto o torna um filtro, não um ignore global. Correção: Sempre coloque ignores globais em seu próprio objeto { ignores: [...] }.
Desempenho em projetos grandes - npx next lint apenas faz o lint de app/, pages/, components/, lib/ e src/ por padrão. Diretórios personalizados precisam de --dir. Correção: Adicione flags --dir ou configure eslint.dirs em next.config.js.

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 uma única ferramenta rápida para linting e formatação	Você precisa do ecossistema completo de plugins ESLint
`oxlint`	Você quer linting extremamente rápido escrito em Rust	Você precisa de regras personalizadas ou específicas do Next.js
CLI do `eslint` diretamente	Você precisa de controle total sobre quais arquivos são verificados	Você quer padrões padrão cientes do Next.js

FAQs

Por que o Next.js usa FlatCompat em vez de configuração plana nativa?

As predefinições ESLint do Next.js (next/core-web-vitals, next/typescript) ainda usam o formato extends legado internamente.
FlatCompat une essas configurações legadas à configuração plana do ESLint 9.
Assim que o Next.js lançar suporte nativo para configuração plana, FlatCompat não será mais necessário.

Qual é a diferença entre next/core-web-vitals e next/typescript?

next/core-web-vitals agrupa regras de React, hooks, importação e específicas do Next.js com padrões rigorosos.
next/typescript adiciona regras do @typescript-eslint/eslint-plugin ajustadas para Next.js.
A maioria dos projetos estende ambos.

Posso usar um arquivo .eslintrc em vez de eslint.config.mjs?

O ESLint 9 prefere configuração plana (eslint.config.mjs).
Se existirem tanto um .eslintrc.* quanto eslint.config.mjs, o ESLint voltará para o arquivo legado.
Exclua todos os arquivos .eslintrc.* ao migrar para configuração plana para evitar confusão.

Como faço o lint de diretórios fora dos padrões do Next.js?

# O Next.js apenas faz o lint de app/, pages/, components/, lib/, src/ por padrão
npx next lint --dir src --dir utils --dir services

O que o modo --strict faz em next lint?

Ele trata todos os avisos como erros.
Qualquer regra definida como "warn" agora falhará na execução do lint.
Útil para CI onde você quer tolerância zero para avisos.

Armadilha: Por que o ESLint ignora meu padrão de ignores globais?

Na configuração plana, ignores só funciona como um ignore global quando é a única chave em seu objeto de configuração.
Se você misturar ignores com rules no mesmo objeto, ele age como um filtro de arquivo, não um ignore global.
Sempre coloque ignores globais em um objeto { ignores: [...] } separado.

Como suprimo erros de variável não utilizada para parâmetros de função em TypeScript?

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

Prefira parâmetros não utilizados com _ e eles serão ignorados.

Qual é o propósito da configuração __filename e __dirname em eslint.config.mjs?

Módulos ES não têm globais __filename ou __dirname.
fileURLToPath(import.meta.url) e dirname() os recriam.
FlatCompat requer baseDirectory para resolver caminhos de configuração relativos.

Como faço a verificação de tipo do próprio arquivo de configuração ESLint?

eslint.config.mjs é JavaScript puro, não TypeScript.
Você pode adicionar // @ts-check no topo e usar anotações JSDoc para verificação básica de tipo.
Alternativamente, use eslint.config.ts com suporte experimental de configuração TypeScript no ESLint 9.

Armadilha: Por que a primeira execução de npx next lint me pede para escolher uma configuração?

O Next.js exibe um assistente de configuração na primeira execução se nenhum arquivo de configuração ESLint existir.
Para evitar isso, crie eslint.config.mjs antes de executar npx next lint.
Escolha "Strict" no assistente para obter os padrões next/core-web-vitals.

Posso executar o ESLint diretamente em vez de usar next lint?

# ESLint direto (ignora os padrões de diretório do Next.js)
npx eslint . --fix
 
# next lint (respeita os padrões de diretório do Next.js)
npx next lint --fix

Use npx eslint . quando precisar de controle total sobre quais arquivos são verificados.

Como adiciono suporte a alias de caminho do TypeScript ao ESLint?

A predefinição next/typescript configura o analisador TypeScript automaticamente.
Alias de caminho como @/* definidos em tsconfig.json são resolvidos pelo analisador.
Nenhuma configuração ESLint adicional é necessária para alias de caminho em um projeto Next.js.

Relacionado

Regras Essenciais do ESLint - configure regras individuais
Plugins ESLint - adicione plugins para React, TypeScript, acessibilidade
Integração ESLint + Prettier - evite conflitos de formatação
Linting em CI/CD - execute o ESLint no GitHub Actions

Receita

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

# Instale o ESLint (incluído com create-next-app)
npm install --save-dev eslint eslint-config-next
 
# Execute o linting via CLI do Next.js
npx next lint
 
# Execute o linting e corrija automaticamente
npx next lint --fix
 
# Execute o linting em diretórios específicos
npx next lint --dir src --dir app

Quando usar isso: Todo projeto Next.js deve ter o ESLint configurado desde o primeiro dia.

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: {
      // Personalize as regras aqui
      "@typescript-eslint/no-unused-vars": [
        "error",
        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
      ],
      "react/no-unescaped-entities": "off",
    },
  },
  {
    ignores: [
      "node_modules/",
      ".next/",
      "out/",
      "public/",
      "coverage/",
    ],
  },
];
 
export default eslintConfig;

O que isso demonstra:

Formato de configuração plana do ESLint 9 usando eslint.config.mjs
Uso do FlatCompat para unir configurações do Next.js (que ainda usam o formato legado) à configuração plana
Extensão de next/core-web-vitals (inclui regras de React, hooks e importação) e next/typescript
Personalização de uma regra e ignorar diretórios

Análise Detalhada

Como Funciona

O Next.js vem com sua própria integração ESLint via npx next lint
A predefinição next/core-web-vitals agrupa eslint-plugin-react, eslint-plugin-react-hooks, eslint-plugin-next e eslint-plugin-import com padrões rigorosos
A predefinição next/typescript adiciona regras do @typescript-eslint/eslint-plugin ajustadas para Next.js
O ESLint 9 usa configuração plana (eslint.config.mjs) em vez do formato legado .eslintrc
FlatCompat é uma ponte que permite usar configurações no estilo extends legado dentro da configuração plana - necessário porque as predefinições do Next.js ainda não foram totalmente migradas

Variações

ESLint Autônomo (sem next lint):

# Execute o ESLint diretamente
npx eslint . --fix
 
# Ou via script package.json

{
  "scripts": {
    "lint": "next lint",
    "lint:fix": "next lint --fix",
    "lint:strict": "next lint --strict"
  }
}

Modo Estrito (trata avisos como erros):

npx next lint --strict

Ignorando arquivos:

// Em eslint.config.mjs - bloco de ignores
{
  ignores: [
    "**/*.config.js",
    "**/*.config.mjs",
    "migrations/",
    "generated/",
  ],
}

Notas sobre TypeScript

# A predefinição next/typescript cuida disso automaticamente:
# - @typescript-eslint/parser é configurado
# - Regras cientes de TypeScript são habilitadas
# - Arquivos .ts e .tsx são incluídos por padrão

Armadilhas

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

Configuração plana não detectada - Se o ESLint ignorar seu eslint.config.mjs, você pode ter um arquivo .eslintrc.* sobrando. O ESLint 9 prefere configuração plana, mas volta para o legado se ambos existirem. Correção: Exclua todos os arquivos .eslintrc.* ao usar configuração plana.
Primeira execução solicita configuração - Executar npx next lint pela primeira vez exibe um assistente de configuração. Correção: Escolha "Strict" para next/core-web-vitals ou crie o arquivo de configuração manualmente com antecedência.
Ignores devem ser um objeto separado - Na configuração plana, o array ignores só funciona como um ignore global quando é a única chave em seu objeto de configuração. Misturar ignores com rules no mesmo objeto o torna um filtro, não um ignore global. Correção: Sempre coloque ignores globais em seu próprio objeto { ignores: [...] }.
Desempenho em projetos grandes - npx next lint apenas faz o lint de app/, pages/, components/, lib/ e src/ por padrão. Diretórios personalizados precisam de --dir. Correção: Adicione flags --dir ou configure eslint.dirs em next.config.js.

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 uma única ferramenta rápida para linting e formatação	Você precisa do ecossistema completo de plugins ESLint
`oxlint`	Você quer linting extremamente rápido escrito em Rust	Você precisa de regras personalizadas ou específicas do Next.js
CLI do `eslint` diretamente	Você precisa de controle total sobre quais arquivos são verificados	Você quer padrões padrão cientes do Next.js

FAQs

Por que o Next.js usa FlatCompat em vez de configuração plana nativa?

As predefinições ESLint do Next.js (next/core-web-vitals, next/typescript) ainda usam o formato extends legado internamente.
FlatCompat une essas configurações legadas à configuração plana do ESLint 9.
Assim que o Next.js lançar suporte nativo para configuração plana, FlatCompat não será mais necessário.

Qual é a diferença entre next/core-web-vitals e next/typescript?

next/core-web-vitals agrupa regras de React, hooks, importação e específicas do Next.js com padrões rigorosos.
next/typescript adiciona regras do @typescript-eslint/eslint-plugin ajustadas para Next.js.
A maioria dos projetos estende ambos.

Posso usar um arquivo .eslintrc em vez de eslint.config.mjs?

O ESLint 9 prefere configuração plana (eslint.config.mjs).
Se existirem tanto um .eslintrc.* quanto eslint.config.mjs, o ESLint voltará para o arquivo legado.
Exclua todos os arquivos .eslintrc.* ao migrar para configuração plana para evitar confusão.

Como faço o lint de diretórios fora dos padrões do Next.js?

# O Next.js apenas faz o lint de app/, pages/, components/, lib/, src/ por padrão
npx next lint --dir src --dir utils --dir services

O que o modo --strict faz em next lint?

Ele trata todos os avisos como erros.
Qualquer regra definida como "warn" agora falhará na execução do lint.
Útil para CI onde você quer tolerância zero para avisos.

Armadilha: Por que o ESLint ignora meu padrão de ignores globais?

Na configuração plana, ignores só funciona como um ignore global quando é a única chave em seu objeto de configuração.
Se você misturar ignores com rules no mesmo objeto, ele age como um filtro de arquivo, não um ignore global.
Sempre coloque ignores globais em um objeto { ignores: [...] } separado.

Como suprimo erros de variável não utilizada para parâmetros de função em TypeScript?

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

Prefira parâmetros não utilizados com _ e eles serão ignorados.

Qual é o propósito da configuração __filename e __dirname em eslint.config.mjs?

Módulos ES não têm globais __filename ou __dirname.
fileURLToPath(import.meta.url) e dirname() os recriam.
FlatCompat requer baseDirectory para resolver caminhos de configuração relativos.

Como faço a verificação de tipo do próprio arquivo de configuração ESLint?

eslint.config.mjs é JavaScript puro, não TypeScript.
Você pode adicionar // @ts-check no topo e usar anotações JSDoc para verificação básica de tipo.
Alternativamente, use eslint.config.ts com suporte experimental de configuração TypeScript no ESLint 9.

Armadilha: Por que a primeira execução de npx next lint me pede para escolher uma configuração?

O Next.js exibe um assistente de configuração na primeira execução se nenhum arquivo de configuração ESLint existir.
Para evitar isso, crie eslint.config.mjs antes de executar npx next lint.
Escolha "Strict" no assistente para obter os padrões next/core-web-vitals.

Posso executar o ESLint diretamente em vez de usar next lint?

# ESLint direto (ignora os padrões de diretório do Next.js)
npx eslint . --fix
 
# next lint (respeita os padrões de diretório do Next.js)
npx next lint --fix

Use npx eslint . quando precisar de controle total sobre quais arquivos são verificados.

Como adiciono suporte a alias de caminho do TypeScript ao ESLint?

A predefinição next/typescript configura o analisador TypeScript automaticamente.
Alias de caminho como @/* definidos em tsconfig.json são resolvidos pelo analisador.
Nenhuma configuração ESLint adicional é necessária para alias de caminho em um projeto Next.js.

Relacionado

Regras Essenciais do ESLint - configure regras individuais
Plugins ESLint - adicione plugins para React, TypeScript, acessibilidade
Integração ESLint + Prettier - evite conflitos de formatação
Linting em CI/CD - execute o ESLint no GitHub Actions

Configuração do ESLint para Next.js

Buscar na documentação

Configuração do ESLint para Next.js