ESLintプラグイン

Next.jsは、ベース設定にバンドルされているESLintプラグインeslint-plugin-nextを提供しており、Next.jsアプリケーションで一般的な問題を検出することが可能です。

リファレンス

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

これは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	クライアントコンポーネントがasync関数になるのを防止します。
	@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

モノレポ内のルートディレクトリの指定

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

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には、相対パスまたは絶対パス、glob（例：`"packages/*/"）、またはパスやglobの配列を指定できます。

キャッシュの無効化

パフォーマンス向上のため、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設定にeslint-config-prettierを含めることをお勧めします。

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

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

ステージングされたファイルのリンティング

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

.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に設定できます：

import type { NextConfig } from 'next'

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

export default nextConfig

既存設定の移行

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

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

以下の条件がすべて当てはまる場合：

以下のプラグインの1つ以上が既にインストールされている（個別またはairbnbやreact-appなどの別の設定を通じて）：
- react
- react-hooks
- jsx-a11y
- import
Next.js内でBabelが設定されている方法とは異なる特定の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プラグインから直接拡張することを推奨します。

On this page