ESLint

Next.js bietet eine integrierte ESLint-Erfahrung von Haus aus. 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 in Ihrer Anwendung noch nicht 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 planen, eine eigene benutzerdefinierte ESLint-Konfiguration einzurichten.

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 jedes Mal ausführen, wenn Sie ESLint ausführen möchten, um Fehler zu finden. Sobald ESLint eingerichtet ist, 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 Sie nicht möchten, dass ESLint während next build ausgeführt wird, 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 in Ihrer Anwendung noch nicht 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

Dies 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. Der vollständige Regelsatz lautet wie folgt:

In der empfohlenen Konfiguration aktiviert

Wenn ESLint in Ihrer Anwendung bereits konfiguriert ist, empfehlen wir, dieses Plugin direkt zu erweitern, anstatt eslint-config-next einzubinden, es sei denn, einige Bedingungen sind erfüllt. Lesen Sie den Abschnitt 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 mithilfe 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)
  },
}

Ähnlich 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 werden, 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 Flag --no-cache 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 wird automatisch für neue Anwendungen eingebunden, die mit Create Next App erstellt werden.

TypeScript

Zusätzlich zu den Next.js-ESLint-Regeln fügt create-next-app --typescript auch TypeScript-spezifische Lint-Regeln mit next/typescript zu Ihrer Konfiguration hinzu:

{
  "extends": ["next/core-web-vitals", "next/typescript"]
}

Diese Regeln basieren auf plugin:@typescript-eslint/recommended. Weitere Details finden Sie unter typescript-eslint > Configs.

Verwendung mit anderen Tools

Prettier

ESLint enthält auch Code-Formatierungsregeln, die mit Ihrer bestehenden Prettier-Einrichtung 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 gestagte Git-Dateien auszuführen, müssen Sie der .lintstagedrc.js-Datei im Stammverzeichnis Ihres Projekts Folgendes 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

Falls Sie ESLint bereits in Ihrer Anwendung konfiguriert haben 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 von der Babel-Konfiguration in Next.js abweichen (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 die Konfiguration innerhalb von eslint-config-next bevorzugen, oder direkt vom Next.js-ESLint-Plugin zu erben:

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

Das Plugin kann normal in Ihrem Projekt installiert werden, ohne next lint ausführen zu müssen:

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

Dadurch wird das Risiko von Kollisionen oder Fehlern vermieden, 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 mit dem Verhalten der next-Konfiguration überschneiden, oder direkt vom Next.js-ESLint-Plugin zu erben, wie oben beschrieben.