Improve custom eslint integration

[askibinski]

I had some trouble with a custom eslint configuration. @KyleAMathews helped me out on Slack and asked me to file an issue to make this easier.

Summary

Gatsby supports using a custom eslint config. The steps are described in the documentation page. However, when you use your own configuration .eslintrc.js file you will lose the build integration with eslint-loader. This will prevent any warnings from apearing in the terminal.

To be fair, this is described in the manual page with a note, and there is a link to a plugin you can use to get the integration back using webpack, but even then it is quite a hassle to get the same rules Gatsby uses back in your own config (in addition to your own config).

Basic example

• First see that the gatsby eslint configurations works:
• Create a component which creates a warning on gatsby develop. (for me it was a video tag without a subtitles track which will trigger a warning from jsx-a11y/media-has-caption.
• You should see warnings in the terminal about this.
• Follow the instructions on the documentation page to create a your custom .eslintrc and add back the rules from gatsby.
• Now you lost the output in the terminal
• Add add the plugin to fix this.
• You should see the warning

Motivation

It would be nice if you could more easily extend Gatsby's eslint config instead of throwing it away and build your own for scratch which leads to unexpected behavior. This is especially cumbersome if you just need one rule added or changed.

[daledesilva]

@askibinski , I've also found this confusing, however, I haven't had even as much success as you.
In your 4th step you note to create .eslintrc and add back the rules from gatsby. What do those rules look like? - as the code they provide is minimal and the file they link to is a TS file that doesn't like being pasted into a JS file. Thanks!

[kelvindecosta]

@askibinski, I completely agree with this. Extending the base configuration can be extremely frustrating.

Firstly, Gatsby updates the base configuration quite often. Even if you did copy their config, it would get outdated soon.
Moreover, the base configuration is dependent on a GraphQL schema variable, requiring yet another plugin for its extraction.

It would be really convenient if Gatsby could extend the .eslintrc configuration instead of overwriting it.

[kelvindecosta]

Overview

Hello @askibinski, @KyleAMathews, @daledesilva

I think I might have figured out how to properly extend most of Gatsby's default ESLint configuration.

Configuration

gatsby-eslint.js

/**
 * Gatsby's Default ESLint Configuration
 */

const { store } = require("gatsby/dist/redux")
const { eslintConfig } = require("gatsby/dist/utils/eslint-config")
const { reactHasJsxRuntime } = require("gatsby/dist/utils/webpack-utils")

//Load GraphQL Schema
const { schema } = store.getState()

module.exports = {
  // Gatsby Default ESLint Configuration
  ...eslintConfig(schema, reactHasJsxRuntime()).baseConfig,

  // Removes `gatsby/src/utils/eslint-rules`
  extends: "react-app",
}

.eslintrc.js

module.exports = {
  // Extend Gatsby's Default ESLint Configuration
  extends: `${__dirname}/gatsby-eslint.js`,

  // Rules
  rules: {
    "graphql/template-strings": "off", // Disabled because it causes an error; Syntax Error: Unexpected <EOF>
  },
}

gatsby-node.js

const ESLintPlugin = require("eslint-webpack-plugin")

exports.onCreateWebpackConfig = ({ stage, actions }) => {
  if (stage === "develop") {
    actions.setWebpackConfig({
      plugins: [
        new ESLintPlugin({
          extensions: ["js", "jsx", "ts", "tsx"], // | [, "md", "mdx"] or any other files
          emitWarning: true,
          failOnError: false,
        }),
      ],
    })
  }
}

To enable gatsby/src/utils/eslint-rules,

• add rulePaths: `${__dirname}/node_modules/gatsby/dist/utils/eslint-rules`
  to the ESLintPlugin options.
• add --rulesdir node_modules/gatsby/dist/utils/eslint-rules to your lint command

You can use gatsby-plugin-eslint (with appropriate options) instead of this step.

Conclusions

• I'd like it if I could specify rulePaths or its equivalent in my .eslintrc.js file.
• graphql/template-strings is causing a Syntax Error that I haven't tackled yet.

Any feedback would be greatly appreciated!

[timbakkum]

indeed, I have a similar setup and you'll get error saying that it can't find the two gatsby specific rules. Any tips would be great. It seems to me like it would be nice if gatsby's eslint config was a plugin that you can extend from so you don't miss out on the custom gatsby rules.

[kelvindecosta]

Hey @timbakkum

As I mentioned above, you can add the rules by providing a rulesPath to ESLintPlugin or using the --rulesdir flag with the CLI.

I decided to bundle these steps into a plugin for convenience.
Any feedback is appreciated!

Thank you

[timbakkum]

Hi @kelvindecosta

What you say works for the command line/browser console eslint output, but it doesn't work for vscode because we can't import the basic gatsby eslint config and rules as an npm package in our own custom .eslintrc.

As far as I'm aware, your plugin does not enable it either, because it only plugs into the webpack eslint process.
I see your repo also has an outstanding issue regarding enabling these rules: kelvindecosta/gatsby-plugin-eslint-config#1 (comment)

[kelvindecosta]

Hey @timbakkum

As long as you also include the plugin in both the gatsby-config.js and .eslintrc.js, VS Code should pick it up.

As for the custom rules, I've tried adding a rulePaths option to the ESLintPlugin but that doesn't work.