Using flat config in monorepo: one config file or multiple?

[yf-yang]

I'm using eslint in a monorepo, where a full eslintrc is placed at the root directory and different packages contain their own eslintrc that extends the root and modify rules if they need to. In this way, whenever I want to change a rule setting, I can first consider if this rule should be generally applied, then navigate to the root config or package config and modify it.

However, when I'm switching to the new flat config system, I notice the blog post states:

In contrast to eslintrc, which allowed multiple config files in multiple locations, multiple config file formats, and even package.json-based configs, flat config has just one location for all of your project’s configuration: the eslint.config.js file. By limiting configuration to one location and one format, we can take advantage of the JavaScript runtime’s loading mechanism directly and avoid the need for custom parsing of config files.

Does it mean the recommended way is to move all the package-wise eslint config to the root? What is the recommended way in a monorepo scenario and why?

[Rec0iL99]

Hi @yf-yang, before using the flat config, the common structure developers followed in monorepos was having a root .eslintrc.* and then having individual .eslintrc.*s in different packages of the monorepo extending the root config just like how you described.

With flat config you would need just one eslint.config.js with all configurations at the root of your monorepo.

File structure:

project/
    eslint.config.js
    packages/
        api/
            index.js
        frontend/
            index.js

You can use glob patterns in the files keys to define configs for individual packages of your monorepo:

// eslint.config.js
export default [
    {
        files: ["api/**/*.js"],
        rules: {
            "semi": "error",
            "no-unused-vars": "error"
        }  
    },
    {
        files: ["frontend/**/*.js"],
        rules: {
            "no-undef": "error",
            "semi": "warn"
        }  
    }
];

In this way ESLint will use the second config for linting any js file in your frontend package.

You can also have a config that would be used for every js file in your project.

// eslint.config.js
export default [
    {
        files: ["**/*.js"],
        rules: {
           "no-unused-vars": "warn"
        }
    },
    {
        files: ["api/**/*.js"],
        rules: {
            "semi": "error",
            "no-unused-vars": "error"
        }  
    },
    {
        files: ["frontend/**/*.js"],
        rules: {
            "no-undef": "error",
            "semi": "warn"
        }  
    }
];

Note: Here ESLint will merge configs from top to bottom, so no-unused-vars would be error for a file in api/ instead of warn defined in the config that applies to all files.

Note: ESLint uses minimatch based glob patterns to match files defined in the files keys.

> const minimatch = require("minimatch")
> minimatch('api/index.js', 'api/**/*.js')
true
> minimatch('api/resolvers/index.js', 'api/**/*.js')
true
> minimatch('api/index.js', '**/*.js')
true
> minimatch('frontend/components/index.js', 'api/**/*.js')
false

You can track the complete implementation of the flat config at #13481

The ESLint team is excited to see users using the new flat config system. Thanks for using ESLint.

[nzakas]

To echo what @Rec0iL99 said: we don't have any official recommended way to do this. We think it makes sense to use just one eslint.config.js file at the root, and it is definitely possible, but we don't know for 100% sure if it's what makes the most sense for most monorepos.

[eakl]

Thanks @Rec0iL99 . I know I CAN use one flat config for all the monorepos and how, but the key is, is it the recommended way to do so? There are at least 3 reasons that I want to use a config per child repo:

1. I'm using TypeScript (typescript-eslint), where each child repo has an independent tsconfig (so I need to designate languageOptions.parserOptions.project for each folder). By putting one config per directory, I can directly copy a single file without the need to change anything.
2. I'm using vscode workspace folders per child repo, so it would be very natural to specify the folder path exactly once, then navigate to the folder in the sidebar and modify the config file for the repo only.
   So actually I would like to know if there is a strong reason that people should actually merge all of their distributive per-folder config into a single one? After all, we know we can still use the per-folder config structure even with the new flat config system.

I second that. I have trouble using an eslint.config.js per child repo. Given that they have independent tsconfig.json and/or independent .vscode folder, I think being able to co-locate a different config per child repo makes sense in the context of monorepo.

[MikhailShibaev]

What I should do if I need specific rules for my vue3 front and api with fastify/ts without merging? Use eslintrc.*?

[kirkobyte]

I think it would be unfortunate to have a single config file for monorepos. It's nice for teams in a monorepo to have visibility and ownership over the rules applied to their part of the repo.

I can't speak to all monorepo frameworks, but NX sets up configuration files for each tool in each package (including ESLint currently).

Maybe something similar to Jest's "projects" configuration would be suitable to help enable this? https://jestjs.io/docs/configuration#projects-arraystring--projectconfig

[jakebailey]

In #17853, I explained why I wanted eslint.config.mjs to work, and that involved the DefintielyTyped monorepo where each package's package.json type setting was not under our control (as they must match the real package being typed). I had no idea at the time that you basically can't have more than one config file in a monorepo and have to stick one at the root. Super unfortunate.

What prevents eslint from doing what it used to do and instead for each file, figure out which config is the nearest?

[eakl]

In the following monorepo eslint-flat-vscode-playground, ESLint cannot properly find the eslint.config.js located in each playground workspaces

~/d/t/eslint-flat-vscode-playground main ❯ pnpm eslint .

Oops! Something went wrong! :(

ESLint: 8.36.0

ESLint couldn't find a configuration file. To set up a configuration file for this project, please run:

    npm init @eslint/config

ESLint looked for configuration files in /Users/eliasaboukhalillanvin/dev/test/eslint-flat-vscode-playground/dist and its ancestors. If it found none, it then looked in your home directory.

If you think you already have a configuration file or if you need more help, please stop by the ESLint Discord server: https://eslint.org/chat

[Rec0iL99]

Sorry, we lost track of this. If this issue still occurs, can you please open a new help post on our Discord server.

[k35o]

@Rec0iL99
How about this conclusion?
Is it better to use one config file even if it is monorepo?

[lkraav]

Yes.

#16960 (comment) should probably be marked as Answer.

[daniellmiranda]

I've encountered a scenario involving a sharable flat config in a monorepo, and if I understand correctly, this solution wouldn't work 100% (#16960 (comment)).

With the new flat config, we can have many configuration objects cascading inside the array, and this is usually the case in a sharable config. For example:

export default [
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  ...tseslint.configs.stylistic,
  {
    rules: {
      'some-rule': 'off',
    },
  },
  eslintPluginPrettierRecommended,
];

In this specific scenario, I have 2 sharable configs (node and react) similar to the example above. I would need to set a glob pattern in the files: [] key for every configuration object in each sharable config so that the node sharable config only applies to "package-a" and the react sharable config only applies to "package-b".

This is the solution I'm using:

import sharableConfig from 'custom-eslint-config';

const nodeConfig = sharableConfig.configs.node.map(configObject => ({ files: ['packages/package-a/**/*'], ...configObject }));
const reactConfig = sharableConfig.configs.react.map(configObject => ({ files: ['packages/package-b/**/*'], ...configObject }));

export default [...nodeConfig, ...reactConfig];

Does this make sense? I think this is not the best approach, and I would appreciate any suggestions for a better way to do this. I feel like I may be missing something.

[chyzwar]

I have simmilar scenario. Suggested workaround would not work because my shared config have rules for disableTypeChecked on specific files. I also have multiple "node" packages in repo with diffrent locations of tsconfig.

[boris-egorov-ziiina]

@Rec0iL99

Since flatconfigs are just plain JavaScript values exported from modules, does the following setup make sense for monorepo environments?

We have packages/our-eslint-config package that exports base config that's used project-wide:

export default [
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  // project-wide configuration goes here
]

Now, each package that needs eslint has our-eslint-config as its dev dependency listed, and eslint.config.js in on package level defined as

import baseConfig from "our-eslint-config";

export default [
   ...baseConfig,
   // package - specific configuration goes here
]

Actual lint runs can be triggered from each package as local eslint invocation that points to the local config.

[boris-egorov-ziiina]

@jakebailey That's fine for my use case, I will prefer to trigger project-wide lint runs as yarn workspaces foreach ... or some similar option, because ways linting implemented in each package may differ.

[avanderbergh]

I have a monorepo setup (pnpm workspaces) but opted for a single eslint.config.js in the root.

The config makes it easy to set rules for each package as well as share some across packages.

I used https://github.com/typescript-eslint/typescript-eslint as an example. It's also a monorepo with a single eslint config.

[cfthody]

I have a monorepo setup (yarn workspaces) but the configuration is slight different.
I have a packages/eslint with the configurations in the eslint.config.js file that I will use for the differents projects and on the folder root I installed this package as a dev dependency and hadanother eslint.config.js file that does just

import config from "@hubeyetower/eslint";

export default config;

But this seems not to works :/.

[boris-egorov-ziiina]

@cfthody Is the eslint.config.js in your @hubeyetower/eslint package marked as default export from the package via "main" field of package.json file?

[cfthody]

@boris-egorov-ziiina yes, I am marking this file as the default export of the package