ESLint プラグイン

Next.js は、Next.js アプリケーションで一般的な問題を検出するための ESLint プラグイン、eslint-plugin-next を提供しています。このプラグインは基本設定にすでにバンドルされています。

参照

以下の ESLint プラグインからの推奨ルールセットはすべて eslint-config-next 内で使用されています：

これは next.config.js の設定よりも優先されます。

ルール

ルールの完全なセットは以下の通りです：

推奨設定で有効	ルール	説明
	@next/next/google-font-display	Google Fonts での font-display の動作を強制します
	@next/next/google-font-preconnect	Google Fonts で `preconnect` が使用されていることを確認します
	@next/next/inline-script-id	インラインコンテンツを持つ `next/script` コンポーネントに `id` 属性を強制します
	@next/next/next-script-for-ga	Google Analytics のインラインスクリプトを使用する際に `next/script` コンポーネントを推奨します
	@next/next/no-assign-module-variable	`module` 変数への代入を防ぎます
	@next/next/no-async-client-component	client component を非同期関数にすることを防ぎます
	@next/next/no-before-interactive-script-outside-document	`pages/_document.js` の外で `next/script` の `beforeInteractive` 戦略を使用することを防ぎます
	@next/next/no-css-tags	手動のスタイルシートタグを防ぎます
	@next/next/no-document-import-in-page	`pages/_document.js` の外で `next/document` をインポートすることを防ぎます
	@next/next/no-duplicate-head	`pages/_document.js` で `<Head>` を重複して使用することを防ぎます
	@next/next/no-head-element	`<head>` 要素の使用を防ぎます
	@next/next/no-head-import-in-document	`pages/_document.js` で `next/head` を使用することを防ぎます
	@next/next/no-html-link-for-pages	内部の Next.js ページに移動するために `<a>` 要素を使用することを防ぎます
	@next/next/no-img-element	LCP が遅くなり、帯域幅が増えるため `<img>` 要素の使用を防ぎます
	@next/next/no-page-custom-font	ページ専用のカスタムフォントを防ぎます
	@next/next/no-script-component-in-head	`next/head` コンポーネントで `next/script` を使用することを防ぎます
	@next/next/no-styled-jsx-in-document	`pages/_document.js` で `styled-jsx` を使用することを防ぎます
	@next/next/no-sync-scripts	同期スクリプトを防ぎます
	@next/next/no-title-in-document-head	`next/document` の `Head` コンポーネントで `<title>` を使用することを防ぎます
	@next/next/no-typos	Next.js のデータ取得関数での一般的なタイプミスを防ぎます
	@next/next/no-unwanted-polyfillio	Polyfill.io からの重複したポリフィルを防ぎます

開発中にコードエディタで警告やエラーを直接確認するために、適切な統合を使用することをお勧めします。

例

カスタムディレクトリとファイルのリント

デフォルトでは、Next.js は pages/、app/、components/、lib/、および src/ ディレクトリ内のすべてのファイルに対して ESLint を実行します。ただし、next.config.js の eslint 設定で dirs オプションを使用して、プロダクションビルド時にどのディレクトリを指定するかを指定できます：

next.config.js
module.exports = {
  eslint: {
    dirs: ['pages', 'utils'], // プロダクションビルド時（next build）に 'pages' と 'utils' ディレクトリでのみ ESLint を実行します
  },
}

同様に、next lint の --dir および --file フラグを使用して、特定のディレクトリとファイルをリントできます：

Terminal

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

モノレポ内での root ディレクトリの指定

Next.js が root ディレクトリにインストールされていないプロジェクト（モノレポなど）で eslint-plugin-next を使用している場合、.eslintrc の settings プロパティを使用して Next.js アプリケーションの場所を eslint-plugin-next に伝えることができます：

eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname は Node.js v20.11.0 以降で利用可能です
  baseDirectory: import.meta.dirname,
})

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

export default eslintConfig

rootDir はパス（相対または絶対）、グロブ（例："packages/*/"）、またはパスやグロブの配列にすることができます。

キャッシュの無効化

パフォーマンスを向上させるために、ESLint によって処理されたファイルの情報はデフォルトでキャッシュされます。これは .next/cache または定義されたビルドディレクトリに保存されます。単一のソースファイルの内容以上に依存する ESLint ルールを含めており、キャッシュを無効にする必要がある場合は、next lint に --no-cache フラグを使用します。

Terminal

next lint --no-cache

ルールの無効化

サポートされているプラグイン（react、react-hooks、next）によって提供されるルールを変更または無効化したい場合は、.eslintrc の rules プロパティを使用して直接変更できます：

eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname は Node.js v20.11.0 以降で利用可能です
  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

Core Web Vitals と共に

next/core-web-vitals ルールセットは、next lint が初めて実行され、strict オプションが選択されたときに有効になります。

eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname は Node.js v20.11.0 以降で利用可能です
  baseDirectory: import.meta.dirname,
})

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

export default eslintConfig

next/core-web-vitals は、Core Web Vitals に影響を与える場合、デフォルトで警告となるいくつかのルールをエラーに更新します。

next/core-web-vitals エントリポイントは、Create Next App で構築された新しいアプリケーションに自動的に含まれます。

TypeScript と共に

Next.js ESLint ルールに加えて、create-next-app --typescript は next/typescript を使用して TypeScript 固有のリントルールも設定に追加します：

eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname は Node.js v20.11.0 以降で利用可能です
  baseDirectory: import.meta.dirname,
})

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

export default eslintConfig

これらのルールは plugin:@typescript-eslint/recommended に基づいています。詳細は typescript-eslint > Configs を参照してください。

Prettier と共に

ESLint にはコードフォーマットルールも含まれており、既存の Prettier 設定と競合する可能性があります。ESLint と Prettier を連携させるために、eslint-config-prettier を ESLint 設定に含めることをお勧めします。

まず、依存関係をインストールします：

Terminal
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

次に、既存の ESLint 設定に prettier を追加します：

eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname は Node.js v20.11.0 以降で利用可能です
  baseDirectory: import.meta.dirname,
})

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

export default eslintConfig

ステージされたファイルでのリントの実行

ステージされた git ファイルでリントを実行するために lint-staged と共に next lint を使用したい場合は、--file フラグの使用を指定するためにプロジェクトの root にある .lintstagedrc.js ファイルに以下を追加する必要があります。

.lintstagedrc.js
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],
}

プロダクションビルド中のリントの無効化

next build 中に ESLint を実行したくない場合は、next.config.js の eslint.ignoreDuringBuilds オプションを true に設定できます：

TypeScript
JavaScript

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  eslint: {
    // 警告: これにより、プロジェクトに ESLint エラーがあってもプロダクションビルドが正常に完了するようになります。
    ignoreDuringBuilds: true,
  },
}

export default nextConfig

next.config.js
const nextConfig = {
  eslint: {
    // 警告: これにより、プロジェクトに ESLint エラーがあってもプロダクションビルドが正常に完了するようになります。
    ignoreDuringBuilds: true,
  },
}

export default nextConfig

既存の設定の移行

すでにアプリケーションで ESLint を設定している場合、いくつかの条件が満たされない限り、eslint-config-next を含めるのではなく、このプラグインから直接拡張することをお勧めします。

推奨プラグインルールセット

次の条件が真である場合：

以下のプラグインのいずれかをすでにインストールしている（airbnb や react-app などの別の設定を通じて、または個別に）：
- react
- react-hooks
- jsx-a11y
- import
Babel が Next.js 内で設定されている方法と異なる特定の parserOptions を定義している（Babel 設定をカスタマイズしている場合を除き、これは推奨されません）
Node.js および/または TypeScript リゾルバを使用してインポートを処理するために eslint-plugin-import をインストールしている

この場合、これらのプロパティが eslint-config-next 内でどのように設定されているかを好む場合は、これらの設定を削除するか、Next.js ESLint プラグインから直接拡張することをお勧めします：

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

プラグインは、next lint を実行する必要なく、通常どおりプロジェクトにインストールできます：

Terminal
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

これにより、複数の設定で同じプラグインやパーサーをインポートすることによる衝突やエラーのリスクが排除されます。

追加の設定

すでに別の ESLint 設定を使用していて eslint-config-next を含めたい場合は、他の設定の後に最後に拡張されるようにしてください。例えば：

eslint.config.mjs
import js from '@eslint/js'
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({
  // import.meta.dirname は Node.js v20.11.0 以降で利用可能です
  baseDirectory: import.meta.dirname,
  recommendedConfig: js.configs.recommended,
})

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

export default eslintConfig

next 設定は、parser、plugins、および settings プロパティのデフォルト値を設定することをすでに処理しています。これらのプロパティを手動で再宣言する必要はありませんが、使用ケースに応じて異なる設定が必要な場合を除きます。

他の共有可能な設定を含める場合は、これらのプロパティが上書きまたは変更されないようにする必要があります。それ以外の場合は、next 設定と動作を共有する設定を削除するか、上記のように Next.js ESLint プラグインから直接拡張することをお勧めします。

参照​

ルール​

例​

カスタムディレクトリとファイルのリント​

モノレポ内での root ディレクトリの指定​

キャッシュの無効化​

ルールの無効化​

Core Web Vitals と共に​

TypeScript と共に​

Prettier と共に​

ステージされたファイルでのリントの実行​

プロダクションビルド中のリントの無効化​

既存の設定の移行​

推奨プラグインルールセット​

追加の設定​

参照

ルール

例