Velocizzare ESLint nei progetti Next.js con Flat Config e GitLab CI

Questo articolo si concentra su GitLab e mostra come rendere ESLint rapido e prevedibile in un progetto Next.js + TypeScript usando il moderno formato flat config.

Vedremo come:

• Usare esclusioni globali per saltare cartelle pesanti o generate.
• Mantenere un job GitLab CI semplice che esegue npm run lint.

Perché Flat Config?

Il sistema flat config è il formato di configurazione di nuova generazione di ESLint. Sostituisce .eslintrc ed è progettato per essere più veloce, pulito e prevedibile.

Questo sistema:

• Funziona nativamente con i moduli ES.
• Semplifica molto le esclusioni globali e i pattern mirati per i file.
• Si integra facilmente con Next.js (next lint lo supporta direttamente).

Esclusioni globali (ignores al livello principale)

Definisci un blocco ignores al livello principale affinché ESLint non prenda mai in considerazione directory pesanti o generate:

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

Cosa sono queste cartelle e perché ignorarle

• "node_modules/" → dipendenze (ignorate per impostazione predefinita da ESLint).
• ".git/" → metadati del controllo di versione (ignorati per impostazione predefinita da ESLint).
• ".next/" → output della compilazione Next.js (server/client), generato.
• "out/" → output dell’esportazione statica, generato.
• "dist/", "build/" → output compilato o raggruppato in bundle, generato.
• "coverage/" → rapporti di copertura dei test, generati.

Escludendole, ESLint evita di attraversare file irrilevanti, rendendo le esecuzioni del linting più rapide.

Script di package.json

Mantieni gli script semplici e adatti alla CI:

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

next lint integra automaticamente ESLint con impostazioni predefinite sensate per Next.js e rispetta la tua flat config.

GitLab CI: semplice e veloce

Ecco una configurazione minima di GitLab CI che installa le dipendenze ed esegue ESLint:

# .gitlab-ci.yml

stages:
  - lint

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

Note

• npm ci garantisce installazioni riproducibili (basate sul tuo lockfile).
• Il job di linting rimane leggero e si affida interamente alla flat config di ESLint per la velocità. È tutto, una configurazione ESLint pulita, veloce e manutenibile per il tuo progetto Next.js su GitLab CI.