ESLint

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.

Referenz

Die empfohlenen Regel-Sets 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.

Regeln

Die vollständige Liste der Regeln lautet wie folgt:

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

Beispiele

Linting für benutzerdefinierte 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 Option dirs 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 der 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

Angeben eines Stammverzeichnisses in einem Monorepo

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 sich Ihre Next.js-Anwendung befindet, indem Sie die settings-Eigenschaft in Ihrer .eslintrc verwenden:

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname ist ab Node.js v20.11.0 verfügbar
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next'],
    settings: {
      next: {
        rootDir: 'packages/my-app/',
      },
    },
  }),
]

export default eslintConfig

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

Deaktivieren des Caches

Um die Leistung zu verbessern, werden Informationen über von ESLint verarbeitete Dateien 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:

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname ist ab Node.js v20.11.0 verfügbar
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next'],
    rules: {
      'react/no-unescaped-entities': 'off',
      '@next/next/no-page-custom-font': 'off',
    },
  }),
]

export default eslintConfig

Mit Core Web Vitals

Das Regel-Set next/core-web-vitals wird aktiviert, wenn next lint zum ersten Mal ausgeführt wird und die Option strict ausgewählt ist.

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname ist ab Node.js v20.11.0 verfügbar
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next/core-web-vitals'],
  }),
]

export default eslintConfig

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 Einstiegspunkt next/core-web-vitals wird automatisch für neue Anwendungen hinzugefügt, die mit Create Next App erstellt werden.

Mit 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:

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname ist ab Node.js v20.11.0 verfügbar
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next/core-web-vitals', 'next/typescript'],
  }),
]

export default eslintConfig

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

Mit Prettier

ESLint enthält auch Code-Formatierungsregeln, die mit Ihrer bestehenden Prettier-Einrichtung kollidieren 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:

import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname ist ab Node.js v20.11.0 verfügbar
  baseDirectory: import.meta.dirname,
})

const eslintConfig = [
  ...compat.config({
    extends: ['next', 'prettier'],
  }),
]

export default eslintConfig

Linting für gestagte Dateien ausführen

Wenn Sie next lint mit lint-staged verwenden möchten, um den Linter für gestagte Git-Dateien auszuführen, müssen Sie der Datei .lintstagedrc.js 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],
}

Deaktivieren des Lintings während der Produktions-Builds

Wenn Sie nicht möchten, dass ESLint während next build ausgeführt wird, können Sie die Option eslint.ignoreDuringBuilds in next.config.js auf true setzen:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  eslint: {
    // Warnung: Dies ermöglicht den erfolgreichen Abschluss von Produktions-Builds, auch wenn
    // Ihr Projekt ESLint-Fehler aufweist.
    ignoreDuringBuilds: true,
  },
}

export default nextConfig

Migration bestehender Konfigurationen

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

Empfohlenes Plugin-Regel-Set

Wenn die folgenden Bedingungen zutreffen:

• 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 Imports zu verarbeiten

Dann empfehlen wir entweder, diese Einstellungen zu entfernen, wenn Sie die Eigenschaften 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 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 aufgrund des Imports 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 zuletzt nach anderen Konfigurationen erweitert wird. Beispiel:

import js from '@eslint/js'
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname ist ab Node.js v20.11.0 verfügbar
  baseDirectory: import.meta.dirname,
  recommendedConfig: js.configs.recommended,
})

const eslintConfig = [
  ...compat.config({
    extends: ['eslint:recommended', 'next'],
  }),
]

export default eslintConfig

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 abweichende 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.