ESLint

Next.js bietet eine integrierte ESLint-Erfahrung direkt out of the box. 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

Es kann eine der folgenden drei Optionen ausgewählt werden:

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

  .eslintrc.json

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

• Basis: Enthält Next.js' ESLint-Basiskonfiguration.

  .eslintrc.json

  {
    "extends": "next"
  }

• Abbrechen: Enthält keine ESLint-Konfiguration. Wählen Sie diese Option nur, wenn Sie eine eigene individuelle 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 mit der ausgewählten Konfiguration.

Sie können jetzt next lint jedes Mal ausführen, wenn Sie ESLint zur Fehlererkennung nutzen möchten. Sobald ESLint eingerichtet ist, wird es auch automatisch bei jedem Build (next build) ausgeführt. Fehler führen zum Buildabbruch, Warnungen hingegen nicht.

Wenn Sie nicht möchten, dass ESLint während next build ausgeführt wird, lesen Sie die Dokumentation zum Ignorieren von ESLint.

Wir empfehlen, eine geeignete Integration zu verwenden, um Warnungen und Fehler direkt während der Entwicklung in Ihrem Code-Editor anzuzeigen.

ESLint-Konfiguration

Die Standardkonfiguration (eslint-config-next) enthält alles, was Sie für eine optimale ESLint-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 Sie dies ohne Konflikte umsetzen können.

Empfohlene Regelsets der folgenden ESLint-Plugins werden alle in eslint-config-next verwendet:

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

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

ESLint-Plugin

Next.js stellt ein ESLint-Plugin, eslint-plugin-next, bereit, das bereits in der Basiskonfiguration enthalten ist und es ermöglicht, häufige Probleme in einer Next.js-Anwendung zu erkennen. Der vollständige Regelsatz ist wie folgt:

In der empfohlenen Konfiguration aktiviert

Wenn Sie ESLint bereits in Ihrer Anwendung konfiguriert haben, empfehlen wir, direkt von diesem Plugin zu erweitern, anstatt eslint-config-next zu verwenden, es sei denn, einige Bedingungen sind erfüllt. Weitere Informationen finden Sie unter Empfohlene Plugin-Regelsatz.

Benutzerdefinierte Einstellungen

rootDir

Wenn Sie eslint-plugin-next in einem Projekt verwenden, in dem Next.js nicht in Ihrem Stammverzeichnis installiert ist (z.B. in einem Monorepo), können Sie eslint-plugin-next mitteilen, wo Ihre Next.js-Anwendung zu finden ist, 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.

Benutzerdefinierte Verzeichnisse und Dateien überprüfen

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 angeben, welche Verzeichnisse Sie in der ESLint-Konfiguration in next.config.js für Produktions-Builds verwenden möchten:

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

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

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

Zwischenspeicherung

Zur Leistungsverbesserung werden Informationen von ESLint verarbeiteter Dateien standardmäßig zwischengespeichert. Dies wird 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

Regeln deaktivieren

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

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

Core Web Vitals

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

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

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

Der Einstiegspunkt next/core-web-vitals ist für neue Anwendungen, die mit Create Next App erstellt wurden, automatisch enthalten.

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 Einzelheiten finden Sie unter typescript-eslint > Konfigurationen.

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
# or
yarn add --dev eslint-config-prettier
# or
pnpm add --save-dev eslint-config-prettier
# or
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 für gestaged Git-Dateien auszuführen, müssen Sie die folgende Datei .lintstagedrc.js im Stammverzeichnis Ihres Projekts hinzufügen, um die Verwendung des Flags --file 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],
}

Migrieren vorhandener Konfigurationen

Empfohlener Plugin-Regelsatz

Wenn 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 über 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 Importe zu behandeln

Dann empfehlen wir, diese Einstellungen entweder zu entfernen, wenn Sie die Eigenschaften so bevorzugen, wie sie 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 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

Dies beseitigt das Risiko von Konflikten oder Fehlern, die auftreten können, wenn dasselbe Plugin oder derselbe Parser über mehrere Konfigurationen importiert wird.

Zusätzliche Konfigurationen

Wenn Sie bereits eine separate ESLint-Konfiguration verwenden und eslint-config-next einschließen möchten, stellen Sie sicher, dass es zuletzt nach anderen Konfigurationen erweitert wird. Zum Beispiel:

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

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

Wenn Sie weitere teilbare Konfigurationen einschließen, müssen Sie sicherstellen, dass diese Eigenschaften nicht überschrieben oder geändert werden. Andernfalls empfehlen wir, alle Konfigurationen zu entfernen, die Verhalten mit der next-Konfiguration teilen, oder direkt vom Next.js ESLint-Plugin wie oben erwähnt zu erweitern.