Speeding Up ESLint in Next.js Projects with Flat Config and GitLab CI

This post focuses on GitLab and shows how to make ESLint fast and predictable in a Next.js + TypeScript project using the modern flat config format.

We’ll:

• Use global ignores to skip bulky or generated folders.
• Keep a simple GitLab CI job that runs npm run lint.

Why Flat Config?

The flat config system is ESLint’s next-generation configuration format. It replaces .eslintrc and is designed to be faster, cleaner, and more predictable.

It:

• Works natively with ES modules.
• Makes global ignores and targeted file patterns much simpler.
• Integrates smoothly with Next.js (next lint supports it out of the box).

Global Ignores (Top-Level ignores)

Define a top-level ignores block so ESLint never considers bulky or generated directories:

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

What these folders are (and why ignore them)

• "node_modules/" → dependencies (ignored by default by ESLint).
• ".git/" → version control metadata (ignored by default by ESLint).
• ".next/" → Next.js build output (server/client), generated.
• "out/" → static export output, generated.
• "dist/", "build/" → compiled or bundled output, generated.
• "coverage/" → test coverage reports, generated.

By excluding these, ESLint avoids traversing irrelevant files, resulting in faster lint runs.

package.json Scripts

Keep scripts simple and CI-friendly:

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

next lint automatically integrates ESLint with sensible Next.js defaults and respects your flat config.

GitLab CI: Simple and Fast

Here’s a minimal GitLab CI setup that installs dependencies and runs ESLint:

# .gitlab-ci.yml

stages:
  - lint

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

Notes

• npm ci ensures reproducible installs (based on your lockfile).
• The lint job stays lightweight and fully relies on your flat ESLint config for speed. That’s it, a clean, fast, and maintainable ESLint setup for your Next.js project on GitLab CI.