Cómo acelerar ESLint en proyectos Next.js con Flat Config y GitLab CI

Este artículo se centra en GitLab y muestra cómo conseguir que ESLint sea rápido y predecible en un proyecto de Next.js + TypeScript mediante el formato moderno flat config.

Vamos a:

• Usar exclusiones globales para omitir carpetas voluminosas o generadas.
• Mantener una tarea sencilla de GitLab CI que ejecute npm run lint.

¿Por qué Flat Config?

El sistema flat config es el formato de configuración de nueva generación de ESLint. Sustituye a .eslintrc y está diseñado para ser más rápido, claro y predecible.

Este sistema:

• Funciona de forma nativa con módulos ES.
• Simplifica mucho las exclusiones globales y los patrones de archivos específicos.
• Se integra fácilmente con Next.js (next lint lo admite de forma predeterminada).

Exclusiones globales (ignores en el nivel superior)

Define un bloque ignores en el nivel superior para que ESLint nunca tenga en cuenta directorios voluminosos o generados:

// 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
]

Qué son estas carpetas y por qué ignorarlas

• "node_modules/" → dependencias (ESLint las ignora de forma predeterminada).
• ".git/" → metadatos del control de versiones (ESLint los ignora de forma predeterminada).
• ".next/" → salida de compilación de Next.js (servidor/cliente), generada.
• "out/" → salida de exportación estática, generada.
• "dist/", "build/" → salida compilada o empaquetada, generada.
• "coverage/" → informes de cobertura de pruebas, generados.

Al excluirlas, ESLint evita recorrer archivos irrelevantes, lo que acelera las ejecuciones del análisis.

Scripts de package.json

Mantén los scripts sencillos y adecuados para CI:

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

next lint integra automáticamente ESLint con valores predeterminados razonables para Next.js y respeta tu configuración flat config.

GitLab CI: Sencillo y rápido

Esta es una configuración mínima de GitLab CI que instala las dependencias y ejecuta ESLint:

# .gitlab-ci.yml

stages:
  - lint

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

Notas

• npm ci garantiza instalaciones reproducibles (basadas en tu archivo de bloqueo).
• La tarea de análisis sigue siendo ligera y se apoya por completo en tu configuración flat config de ESLint para ganar velocidad. Eso es todo, una configuración de ESLint clara, rápida y fácil de mantener para tu proyecto Next.js en GitLab CI.