{"id":20049,"library":"gatsby-plugin-eslint","title":"gatsby-plugin-eslint","description":"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.","status":"active","version":"4.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/mongkuen/gatsby-plugin-eslint","tags":["javascript","gatsby","gatsby-plugin","eslint"],"install":[{"cmd":"npm install gatsby-plugin-eslint","lang":"bash","label":"npm"},{"cmd":"yarn add gatsby-plugin-eslint","lang":"bash","label":"yarn"},{"cmd":"pnpm add gatsby-plugin-eslint","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"ESLint is the core linting engine; must be installed as peer dependency","package":"eslint","optional":false},{"reason":"Webpack plugin to run ESLint; used by this Gatsby plugin to intercept webpack config","package":"eslint-webpack-plugin","optional":false},{"reason":"Plugin is designed to hook into Gatsby's webpack configuration; required peer dependency","package":"gatsby","optional":false}],"imports":[{"note":"This is a Gatsby plugin, used via gatsby-config.js resolve, not directly imported in components. No ESM/CJS distinction for config.","wrong":"// Incorrect: CommonJS require in gatsby-config.js\nconst plugin = require('gatsby-plugin-eslint');","symbol":"gatsby-plugin-eslint","correct":"// In gatsby-config.js:\nmodule.exports = {\n  plugins: [\n    {\n      resolve: 'gatsby-plugin-eslint',\n      options: { /* ... */ }\n    }\n  ]\n}"},{"note":"eslint-loader is deprecated; this plugin uses eslint-webpack-plugin v2+. Must not use eslint-loader.","wrong":"const ESLintPlugin = require('eslint-loader');","symbol":"eslint-webpack-plugin","correct":"const ESLintPlugin = require('eslint-webpack-plugin');"},{"note":"You must include Gatsby's two required rules explicitly; plugin overwrites default ESLint config entirely.","wrong":"// Omitting Gatsby required rules\n{\n  \"rules\": {}\n}","symbol":"ESLint config","correct":"// .eslintrc.json\n{\n  \"rules\": {\n    \"no-anonymous-exports-page-templates\": \"warn\",\n    \"limited-exports-page-templates\": \"warn\"\n  }\n}"}],"quickstart":{"code":"// Install peer dependencies\nnpm install --save-dev gatsby-plugin-eslint eslint eslint-webpack-plugin\n\n// Create .eslintrc.json in root\n{\n  \"rules\": {\n    \"no-anonymous-exports-page-templates\": \"warn\",\n    \"limited-exports-page-templates\": \"warn\"\n  }\n}\n\n// In gatsby-config.js\nconst path = require('path');\nconst gatsbyRequiredRules = path.join(\n  process.cwd(),\n  'node_modules',\n  'gatsby',\n  'dist',\n  'utils',\n  'eslint-rules'\n);\n\nmodule.exports = {\n  plugins: [\n    {\n      resolve: 'gatsby-plugin-eslint',\n      options: {\n        rulePaths: [gatsbyRequiredRules],\n        stages: ['develop'],\n        extensions: ['js', 'jsx', 'ts', 'tsx'],\n        exclude: ['node_modules', 'bower_components', '.cache', 'public'],\n      },\n    },\n  ],\n};","lang":"javascript","description":"Sets up gatsby-plugin-eslint with required Gatsby rules, overwriting default ESLint config."},"warnings":[{"fix":"Include rulePaths option pointing to Gatsby's built-in ESLint rules directory as shown in the quickstart.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Install eslint-webpack-plugin: npm install --save-dev eslint-webpack-plugin","message":"eslint-loader is deprecated and not supported by this plugin. Use eslint-webpack-plugin instead.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Update to latest version: npm install gatsby-plugin-eslint@latest","message":"Versions prior to 4.0.0 may not support Gatsby v4 or v5. Check compatibility. Current version supports Gatsby v2-v5.","severity":"gotcha","affected_versions":"<4.0.0"},{"fix":"Add desired stages to the options.stages array, e.g., stages: ['develop', 'build-javascript'].","message":"The plugin only works in stages specified in the 'stages' option. Default is ['develop']; lint during build requires adding 'build-javascript' etc.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use traditional .eslintrc format or check plugin documentation for flat config support.","message":"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.","severity":"gotcha","affected_versions":">=4.0.4"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run: npm install --save-dev eslint-webpack-plugin","cause":"eslint-webpack-plugin is not installed or is installed as a devDependency but missing at runtime.","error":"Error: Cannot find module 'eslint-webpack-plugin'"},{"fix":"Replace eslint-loader with eslint-webpack-plugin in your gatsby-config.js and package.json.","cause":"Using deprecated eslint-loader instead of eslint-webpack-plugin.","error":"TypeError: ... is not a function (when using eslint-loader)"},{"fix":"Install the missing plugin: npm install --save-dev eslint-plugin-<name>","cause":"ESLint plugin required by your config is missing or not installed.","error":"ESLint couldn't find the plugin \"eslint-plugin-...\""},{"fix":"Run: npm ls gatsby to check version; adjust rulePaths to node_modules/gatsby/dist/utils/eslint-rules or copy rules manually.","cause":"gatsbyRequiredRules path is incorrect; the ESLint rules directory inside gatsby package has moved or doesn't exist.","error":"Cannot read property 'rules' of undefined (rulePaths)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}