ESLint

Next.js bietet eine integrierte ESLint-Erfahrung direkt nach der Installation. Fügen Sie next lint als Skript zu package.json hinzu:

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

Führen Sie dann npm run lint oder yarn lint aus:

yarn lint

Wenn ESLint noch nicht in Ihrer Anwendung konfiguriert ist, werden Sie durch den Installations- und Konfigurationsprozess geführt.

yarn lint

Sie sehen eine Eingabeaufforderung wie diese:

? Wie möchten Sie ESLint konfigurieren?

❯ Streng (empfohlen)
Basis
Abbrechen

Eine der folgenden drei Optionen kann ausgewählt werden:

• Streng: Enthält die Basis-ESLint-Konfiguration von Next.js zusammen mit einem strengeren Core Web Vitals-Regelsatz. Dies ist die empfohlene Konfiguration für Entwickler, die ESLint zum ersten Mal einrichten.

  {
    "extends": "next/core-web-vitals"
  }

• Basis: Enthält die Basis-ESLint-Konfiguration von Next.js.

  {
    "extends": "next"
  }

• Abbrechen: Enthält keine ESLint-Konfiguration. Wählen Sie diese Option nur, wenn Sie eine eigene benutzerdefinierte ESLint-Konfiguration einrichten möchten.

Wenn eine der beiden Konfigurationsoptionen ausgewählt wird, installiert Next.js automatisch eslint und eslint-config-next als Abhängigkeiten in Ihrer Anwendung und erstellt eine .eslintrc.json-Datei im Stammverzeichnis Ihres Projekts, die Ihre ausgewählte Konfiguration enthält.

Sie können nun next lint ausführen, wann immer Sie ESLint ausführen möchten, um Fehler zu finden. Nachdem ESLint eingerichtet wurde, wird es auch automatisch während jedes Builds (next build) ausgeführt. Fehler führen zum Build-Abbruch, während Warnungen dies nicht tun.

Wenn ESLint nicht während next build ausgeführt werden soll, lesen Sie die Dokumentation zum Ignorieren von ESLint.

Wir empfehlen die Verwendung einer geeigneten Integration, um Warnungen und Fehler direkt in Ihrem Code-Editor während der Entwicklung anzuzeigen.

ESLint-Konfiguration

Die Standardkonfiguration (eslint-config-next) enthält alles, was Sie für eine optimale Linting-Erfahrung in Next.js benötigen. Wenn ESLint noch nicht in Ihrer Anwendung konfiguriert ist, empfehlen wir die Verwendung von next lint, um ESLint zusammen mit dieser Konfiguration einzurichten.

Wenn Sie eslint-config-next zusammen mit anderen ESLint-Konfigurationen verwenden möchten, lesen Sie den Abschnitt Zusätzliche Konfigurationen, um zu erfahren, wie dies ohne Konflikte möglich ist.

Empfohlene Regelsätze der folgenden ESLint-Plugins werden in eslint-config-next verwendet:

• eslint-plugin-react
• eslint-plugin-react-hooks
• eslint-plugin-next

Diese hat Vorrang vor der Konfiguration aus next.config.js.

ESLint-Plugin

Next.js bietet ein ESLint-Plugin, eslint-plugin-next, das bereits in der Basis-Konfiguration enthalten ist und es ermöglicht, häufige Probleme in einer Next.js-Anwendung zu erkennen. Die vollständige Liste der Regeln lautet wie folgt:

In der empfohlenen Konfiguration aktiviert

Wenn ESLint bereits in Ihrer Anwendung konfiguriert ist, empfehlen wir, direkt von diesem Plugin zu erweitern, anstatt eslint-config-next einzubinden, es sei denn, bestimmte Bedingungen sind erfüllt. Lesen Sie Empfohlener Plugin-Regelsatz für weitere Informationen.

Benutzerdefinierte Einstellungen

rootDir

Wenn Sie eslint-plugin-next in einem Projekt verwenden, in dem Next.js nicht im Stammverzeichnis installiert ist (z.B. in einem Monorepo), können Sie eslint-plugin-next mitteilen, wo sich Ihre Next.js-Anwendung befindet, indem Sie die settings-Eigenschaft in Ihrer .eslintrc verwenden:

{
  "extends": "next",
  "settings": {
    "next": {
      "rootDir": "packages/my-app/"
    }
  }
}

rootDir kann ein Pfad (relativ oder absolut), ein Glob (z.B. "packages/*/") oder ein Array von Pfaden und/oder Globs sein.

Linting benutzerdefinierter Verzeichnisse und Dateien

Standardmäßig führt Next.js ESLint für alle Dateien in den Verzeichnissen pages/, app/, components/, lib/ und src/ aus. Sie können jedoch bestimmte Verzeichnisse mit der dirs-Option in der eslint-Konfiguration in next.config.js für Produktions-Builds angeben:

module.exports = {
  eslint: {
    dirs: ['pages', 'utils'], // Führt ESLint nur in den Verzeichnissen 'pages' und 'utils' während Produktions-Builds aus (next build)
  },
}

Ebenso können die Flags --dir und --file für next lint verwendet werden, um bestimmte Verzeichnisse und Dateien zu linten:

next lint --dir pages --dir utils --file bar.js

Caching

Um die Leistung zu verbessern, werden Informationen von Dateien, die von ESLint verarbeitet wurden, standardmäßig zwischengespeichert. Diese werden in .next/cache oder in Ihrem definierten Build-Verzeichnis gespeichert. Wenn Sie ESLint-Regeln verwenden, die von mehr als dem Inhalt einer einzelnen Quelldatei abhängen und den Cache deaktivieren müssen, verwenden Sie das --no-cache-Flag mit next lint.

next lint --no-cache

Deaktivieren von Regeln

Wenn Sie Regeln der unterstützten Plugins (react, react-hooks, next) ändern oder deaktivieren möchten, können Sie dies direkt über die rules-Eigenschaft in Ihrer .eslintrc tun:

{
  "extends": "next",
  "rules": {
    "react/no-unescaped-entities": "off",
    "@next/next/no-page-custom-font": "off"
  }
}

Core Web Vitals

Der next/core-web-vitals-Regelsatz wird aktiviert, wenn next lint zum ersten Mal ausgeführt wird und die Option Streng ausgewählt ist.

{
  "extends": "next/core-web-vitals"
}

next/core-web-vitals aktualisiert eslint-plugin-next, um bei einer Reihe von Regeln, die standardmäßig Warnungen sind, Fehler auszugeben, wenn sie Core Web Vitals beeinflussen.

Der next/core-web-vitals-Einstiegspunkt ist automatisch in neuen Anwendungen enthalten, die mit Create Next App erstellt wurden.

Verwendung mit anderen Tools

Prettier

ESLint enthält auch Code-Formatierungsregeln, die mit Ihrer bestehenden Prettier-Konfiguration in Konflikt geraten können. Wir empfehlen, eslint-config-prettier in Ihre ESLint-Konfiguration aufzunehmen, um ESLint und Prettier zusammenarbeiten zu lassen.

Installieren Sie zunächst die Abhängigkeit:

npm install --save-dev eslint-config-prettier

yarn add --dev eslint-config-prettier

pnpm add --save-dev eslint-config-prettier

bun add --dev eslint-config-prettier

Fügen Sie dann prettier zu Ihrer bestehenden ESLint-Konfiguration hinzu:

{
  "extends": ["next", "prettier"]
}

lint-staged

Wenn Sie next lint mit lint-staged verwenden möchten, um den Linter auf gestagede Git-Dateien auszuführen, müssen Sie Folgendes zur .lintstagedrc.js-Datei im Stammverzeichnis Ihres Projekts hinzufügen, um die Verwendung des --file-Flags anzugeben.

const path = require('path')

const buildEslintCommand = (filenames) =>
  `next lint --fix --file ${filenames
    .map((f) => path.relative(process.cwd(), f))
    .join(' --file ')}`

module.exports = {
  '*.{js,jsx,ts,tsx}': [buildEslintCommand],
}

Migration bestehender Konfigurationen

Empfohlener Plugin-Regelsatz

Wenn ESLint bereits in Ihrer Anwendung konfiguriert ist und eine der folgenden Bedingungen zutrifft:

• Sie haben eines oder mehrere der folgenden Plugins bereits installiert (entweder separat oder durch eine andere Konfiguration wie airbnb oder react-app):
  • react
  • react-hooks
  • jsx-a11y
  • import
• Sie haben spezifische parserOptions definiert, die sich von der Babel-Konfiguration in Next.js unterscheiden (dies wird nicht empfohlen, es sei denn, Sie haben Ihre Babel-Konfiguration angepasst)
• Sie haben eslint-plugin-import mit Node.js- und/oder TypeScript-Resolvern installiert, um Imports zu verarbeiten

Dann empfehlen wir entweder, diese Einstellungen zu entfernen, wenn Sie bevorzugen, wie diese Eigenschaften in eslint-config-next konfiguriert sind, oder direkt vom Next.js ESLint-Plugin zu erweitern:

module.exports = {
  extends: [
    //...
    'plugin:@next/next/recommended',
  ],
}

Das Plugin kann normal in Ihrem Projekt installiert werden, ohne dass next lint ausgeführt werden muss:

npm install --save-dev @next/eslint-plugin-next

yarn add --dev @next/eslint-plugin-next

pnpm add --save-dev @next/eslint-plugin-next

bun add --dev @next/eslint-plugin-next

Dies eliminiert das Risiko von Kollisionen oder Fehlern, die durch das Importieren desselben Plugins oder Parsers über mehrere Konfigurationen hinweg auftreten können.

Zusätzliche Konfigurationen

Falls Sie bereits eine separate ESLint-Konfiguration verwenden und eslint-config-next einbinden möchten, stellen Sie sicher, dass es als letztes nach anderen Konfigurationen erweitert wird. Beispiel:

{
  "extends": ["eslint:recommended", "next"]
}

Die next-Konfiguration übernimmt bereits das Setzen von Standardwerten für die Eigenschaften parser, plugins und settings. Es ist nicht notwendig, diese Eigenschaften manuell neu zu deklarieren, es sei denn, Sie benötigen eine andere Konfiguration für Ihren Anwendungsfall.

Wenn Sie andere gemeinsam nutzbare Konfigurationen einbinden, müssen Sie sicherstellen, dass diese Eigenschaften nicht überschrieben oder modifiziert werden. Andernfalls empfehlen wir, alle Konfigurationen zu entfernen, die sich das Verhalten mit der next-Konfiguration teilen, oder direkt vom Next.js-ESLint-Plugin wie oben erwähnt zu erweitern.