Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
gatsby-plugin-eslint
✓ // In gatsby-config.js:
module.exports = {
plugins: [
{
resolve: 'gatsby-plugin-eslint',
options: { /* ... */ }
}
]
}
✗ // Incorrect: CommonJS require in gatsby-config.js
const plugin = require('gatsby-plugin-eslint');
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
✓ const ESLintPlugin = require('eslint-webpack-plugin');
✗ const ESLintPlugin = require('eslint-loader');
eslint-loader is deprecated; this plugin uses eslint-webpack-plugin v2+. Must not use eslint-loader.
ESLint config
✓ // .eslintrc.json
{
"rules": {
"no-anonymous-exports-page-templates": "warn",
"limited-exports-page-templates": "warn"
}
}
✗ // Omitting Gatsby required rules
{
"rules": {}
}
You must include Gatsby's two required rules explicitly; plugin overwrites default ESLint config entirely.
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'],
},
},
],
};
Errors
Common errors & fixes
Error: Cannot find module 'eslint-webpack-plugin'
eslint-webpack-plugin is not installed or is installed as a devDependency but missing at runtime.
fixRun: npm install --save-dev eslint-webpack-plugin
TypeError: ... is not a function (when using eslint-loader)
Using deprecated eslint-loader instead of eslint-webpack-plugin.
fixReplace eslint-loader with eslint-webpack-plugin in your gatsby-config.js and package.json.
ESLint couldn't find the plugin "eslint-plugin-..."
ESLint plugin required by your config is missing or not installed.
fixInstall the missing plugin: npm install --save-dev eslint-plugin-<name>
Cannot read property 'rules' of undefined (rulePaths)
gatsbyRequiredRules path is incorrect; the ESLint rules directory inside gatsby package has moved or doesn't exist.
fixRun: npm ls gatsby to check version; adjust rulePaths to node_modules/gatsby/dist/utils/eslint-rules or copy rules manually.
Audit
Dependencies
eslintrequiredESLint is the core linting engine; must be installed as peer dependency
eslint-webpack-pluginrequiredWebpack plugin to run ESLint; used by this Gatsby plugin to intercept webpack config
gatsbyrequiredPlugin is designed to hook into Gatsby's webpack configuration; required peer dependency