Acelerando o ESLint em projetos Next.js com Flat Config e GitLab CI

Este artigo se concentra no GitLab e mostra como tornar o ESLint rápido e previsível em um projeto Next.js + TypeScript usando o formato moderno flat config.

Vamos:

• Usar exclusões globais para ignorar pastas volumosas ou geradas.
• Manter uma tarefa simples do GitLab CI que executa npm run lint.

Por que usar Flat Config?

O sistema flat config é o formato de configuração de nova geração do ESLint. Ele substitui .eslintrc e foi projetado para ser mais rápido, organizado e previsível.

Ele:

• Funciona nativamente com módulos ES.
• Simplifica bastante as exclusões globais e os padrões direcionados de arquivos.
• Integra-se facilmente ao Next.js (next lint oferece suporte nativo).

Exclusões globais (ignores no nível superior)

Defina um bloco ignores no nível superior para que o ESLint nunca considere diretórios volumosos ou gerados:

// eslint.config.mjs (flat config)

/** @type {import("eslint").Linter.Config[]} */
export default [
  js.configs.recommended,

  {
    // ESLint already ignores ["**/node_modules/", ".git/"] by default, reference: https://eslint.org/docs/latest/use/configure/configuration-files#globally-ignoring-files-with-ignores
    // so you do NOT need to list them here.
    // The folders below are project-specific outputs we also want to ignore globally.
    ignores: ['.next/**', 'out/**', 'dist/**', 'build/**', 'coverage/**'],
  },
  { ... }, // ... other configuration object, inherit global ignores
]

O que são essas pastas (e por que ignorá-las)

• "node_modules/" → dependências (ignoradas por padrão pelo ESLint).
• ".git/" → metadados de controle de versão (ignorados por padrão pelo ESLint).
• ".next/" → saída da compilação do Next.js (servidor/cliente), gerada.
• "out/" → saída da exportação estática, gerada.
• "dist/", "build/" → saída compilada ou empacotada, gerada.
• "coverage/" → relatórios de cobertura de testes, gerados.

Ao excluir essas pastas, o ESLint evita percorrer arquivos irrelevantes, o que torna as análises mais rápidas.

Scripts de package.json

Mantenha os scripts simples e adequados ao CI:

{
  "scripts": {
    "lint": "next lint"
  }
}

next lint integra automaticamente o ESLint com padrões sensatos do Next.js e respeita sua flat config.

GitLab CI: simples e rápido

Aqui está uma configuração mínima do GitLab CI que instala as dependências e executa o ESLint:

# .gitlab-ci.yml

stages:
  - lint

lint:
  stage: lint
  image: node:20-alpine
  script:
    - npm ci
    - npm run lint

Observações

• npm ci garante instalações reproduzíveis (com base no seu arquivo de lock).
• A tarefa de análise permanece leve e depende inteiramente da sua configuração plana do ESLint para ganhar velocidade. Pronto, uma configuração do ESLint organizada, rápida e fácil de manter para seu projeto Next.js no GitLab CI.