[Feature Request]: Improve documention for new eslint 9 flat configuration for shared monorepo project

[alefduarte]

Is there an existing issue for this?

• I have searched the existing issues and my issue is unique
• My issue appears in the command-line and not only in the text editor

Description Overview

I had some difficulties setting up a shared Eslint 9 flat configuration project in a mono repo structure. I couldn't find clear examples in the documentation, so I ended up creating a configuration file that I'm not entirely confident about.
I created a project @acme/eslint-config with the folllowing index file:

import pluginJs from '@eslint/js';
import reactPlugin from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';
import reactRefresh from 'eslint-plugin-react-refresh';
import globals from 'globals';
import tseslint from 'typescript-eslint';

export default [
  pluginJs.configs.recommended,
  ...tseslint.configs.recommended,
  reactPlugin.configs.flat.recommended,
  reactPlugin.configs.flat['jsx-runtime'],
  {
    files: ['**/*.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}'],
    ignores: ['dist'],
    languageOptions: {
      ecmaVersion: 2020,
      globals: {
        ...globals.serviceworker,
        ...globals.browser,
      },
    },
    settings: { react: { version: '18.3' } },
    plugins: {
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh,
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
    }
  }
];

I initially encountered multiple errors, but it was resolved after using "reactPlugin.configs.flat['jsx-runtime']". However, I'm still unsure about the correctness of my configuration.

In the project where I want to use this configuration, I created an eslint.config.mjs file with the following:

import acmeConfig from '@acme/eslint-config';

export default [...acmeConfig];

This setup is working for me, but I couldn't find a simple tutorial anywhere, only examples using .eslintrc. I'm also uncertain if my configuration is the best for creating documentation on this topic.

I opened this issue in this library because if I removed reactPlugin.configs.flat.recommended, it would work and with it I would always get 'React' must be in scope when using JSX, using reactPlugin.configs.flat['jsx-runtime'] fix it, but it wasn't clear at first.

Expected Behavior

I wanted a clearer tutorial using the new flat config.

eslint-plugin-react version

v7.35.0

eslint version

v9.9.1

node version

v20.10.0

[ljharb]

It sounds like the issue is just that you were confused about the use of jsx-runtime, which is described in the eslintrc section of the readme, but not in [the flat config section(https://github.com/jsx-eslint/eslint-plugin-react?tab=readme-ov-file#flat-configs) of the readme. It's currently written assuming you've read the entire thing, but certainly could be improved.

[dancheb]

I had similar bouts of confusion from the minimal examples for flat config in the README because I wanted to use the flat recommended AND jsx-runtime configs. It isn't as straightforward as extending both with the old .eslintrc method. I found that because the jsx-runtime flat config doesn't turn on (or off) any other rules besides the jsx-runtime related ones, I had to manually merge the configs to get it to work.

  {
    files: ['**/*.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}'],
    ...reactPlugin.configs.flat.recommended,
    ...reactPlugin.configs.flat['jsx-runtime'],
    rules: {
      // Need to combine the rules
      ...reactPlugin.configs.flat.recommended.rules,
      ...reactPlugin.configs.flat['jsx-runtime'].rules
    },
    languageOptions: {
      ...reactPlugin.configs.flat.recommended.languageOptions,
      ...reactPlugin.configs.flat['jsx-runtime'].languageOptions,
      globals: {
        ...globals.browser,
      },
    },
  },

I think you could get away with just spreading the jsx-runtime flat config's languageOptions and the rest of the config, but the rules specifically need to be merged. Definitely wish it was more clear how we should be using both the recommended and jsx-runtime flat configs.

[ljharb]

I'd love a PR to improve the docs here.