gatsby-plugin-eslint

4.0.4 verified Sat Apr 25 auth: no javascript

Gatsby plugin to replace default ESLint Webpack config, giving full control over linting rules in Gatsby projects. Current version 4.0.4 supports Gatsby v2-v5, ESLint 7/8, and eslint-webpack-plugin v2-v4. Overwrites Gatsby default ESLint config entirely; users must manually re-add Gatsby required rules (no-anonymous-exports-page-templates, limited-exports-page-templates) via rulePaths. Works only with eslint-webpack-plugin, not eslint-loader. Key differentiator: enables custom ESLint configuration that would otherwise be overridden by Gatsby's internal setup.

Common errors

error Error: Cannot find module 'eslint-webpack-plugin' ↓

cause eslint-webpack-plugin is not installed or is installed as a devDependency but missing at runtime.

fix

Run: npm install --save-dev eslint-webpack-plugin

error TypeError: ... is not a function (when using eslint-loader) ↓

cause Using deprecated eslint-loader instead of eslint-webpack-plugin.

fix

Replace eslint-loader with eslint-webpack-plugin in your gatsby-config.js and package.json.

error ESLint couldn't find the plugin "eslint-plugin-..." ↓

cause ESLint plugin required by your config is missing or not installed.

fix

Install the missing plugin: npm install --save-dev eslint-plugin-<name>

error Cannot read property 'rules' of undefined (rulePaths) ↓

cause gatsbyRequiredRules path is incorrect; the ESLint rules directory inside gatsby package has moved or doesn't exist.

fix

Run: npm ls gatsby to check version; adjust rulePaths to node_modules/gatsby/dist/utils/eslint-rules or copy rules manually.

Warnings

breaking This plugin completely overwrites Gatsby's ESLint Webpack Plugins. You must manually re-add Gatsby required rules (no-anonymous-exports-page-templates, limited-exports-page-templates) via rulePaths, or lint errors will not be enforced. ↓

fix Include rulePaths option pointing to Gatsby's built-in ESLint rules directory as shown in the quickstart.

deprecated eslint-loader is deprecated and not supported by this plugin. Use eslint-webpack-plugin instead. ↓

fix Install eslint-webpack-plugin: npm install --save-dev eslint-webpack-plugin

gotcha Versions prior to 4.0.0 may not support Gatsby v4 or v5. Check compatibility. Current version supports Gatsby v2-v5. ↓

fix Update to latest version: npm install gatsby-plugin-eslint@latest

gotcha The plugin only works in stages specified in the 'stages' option. Default is ['develop']; lint during build requires adding 'build-javascript' etc. ↓

fix Add desired stages to the options.stages array, e.g., stages: ['develop', 'build-javascript'].

gotcha If you are using ESLint flat config (eslint.config.js), this plugin may not work as it expects a traditional .eslintrc. Flat config is supported only in ESLint >=9 and requires additional configuration. ↓

fix Use traditional .eslintrc format or check plugin documentation for flat config support.

Install

npm install gatsby-plugin-eslint

yarn add gatsby-plugin-eslint

pnpm add gatsby-plugin-eslint

Imports

gatsby-plugin-eslint

wrong

// Incorrect: CommonJS require in gatsby-config.js
const plugin = require('gatsby-plugin-eslint');

correct

// In gatsby-config.js:
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-eslint',
      options: { /* ... */ }
    }
  ]
}

This is a Gatsby plugin, used via gatsby-config.js resolve, not directly imported in components. No ESM/CJS distinction for config.

eslint-webpack-plugin
wrong
```
const ESLintPlugin = require('eslint-loader');
```
correct
```
const ESLintPlugin = require('eslint-webpack-plugin');
```
eslint-loader is deprecated; this plugin uses eslint-webpack-plugin v2+. Must not use eslint-loader.

ESLint config

wrong

// Omitting Gatsby required rules
{
  "rules": {}
}

correct

// .eslintrc.json
{
  "rules": {
    "no-anonymous-exports-page-templates": "warn",
    "limited-exports-page-templates": "warn"
  }
}

You must include Gatsby's two required rules explicitly; plugin overwrites default ESLint config entirely.

Quickstart

Sets up gatsby-plugin-eslint with required Gatsby rules, overwriting default ESLint config.

// Install peer dependencies
npm install --save-dev gatsby-plugin-eslint eslint eslint-webpack-plugin

// Create .eslintrc.json in root
{
  "rules": {
    "no-anonymous-exports-page-templates": "warn",
    "limited-exports-page-templates": "warn"
  }
}

// In gatsby-config.js
const path = require('path');
const gatsbyRequiredRules = path.join(
  process.cwd(),
  'node_modules',
  'gatsby',
  'dist',
  'utils',
  'eslint-rules'
);

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-eslint',
      options: {
        rulePaths: [gatsbyRequiredRules],
        stages: ['develop'],
        extensions: ['js', 'jsx', 'ts', 'tsx'],
        exclude: ['node_modules', 'bower_components', '.cache', 'public'],
      },
    },
  ],
};