Plugin Migration to Flat Config

Beginning in ESLint v9.0.0, the default configuration system will be the new flat config system. In order for your plugins to work with flat config files, you’ll need to make some changes to your existing plugins.

Recommended Plugin Structure

To make it easier to work with your plugin in the flat config system, it’s recommended that you switch your existing plugin entrypoint to look like this:

const plugin = {
    meta: {},
    configs: {},
    rules: {},
    processors: {}
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12

This structure allows the most flexibility when making other changes discussed on this page.

Adding Plugin Meta Information

With the old eslintrc configuration system, ESLint could pull information about the plugin from the package name, but with flat config, ESLint no longer has access to the name of the plugin package. To replace that missing information, you should add a meta key that contains at least a name key, and ideally, a version key, such as:

const plugin = {
    meta: {
        name: "eslint-plugin-example",
        version: "1.0.0"
    },
    configs: {},
    rules: {},
    processors: {}
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

If your plugin is published as an npm package, the name and version should be the same as in your package.json file; otherwise, you can assign any value you’d like.

Without this meta information, your plugin will not be usable with the --cache and --print-config command line options.

Migrating Rules for Flat Config

No changes are necessary for the rules key in your plugin. Everything works the same as with the old eslintrc configuration system.

Migrating Processors for Flat Config

Each processor should specify a meta object. For more information, see the full documentation.

No other changes are necessary for the processors key in your plugin as long as you aren’t using file extension-named processors. If you have any file extension-named processors, you must update the name to a valid identifier (numbers and letters). File extension-named processors were automatically applied in the old configuration system but are not automatically applied when using flat config. Here is an example of a file extension-named processor:

const plugin = {
    configs: {},
    rules: {},
    processors: {

        // no longer supported
        ".md": {
            preprocess() {},
            postprocess() {}
        }
    }
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

The name ".md" is no longer valid for a processor, so it must be replaced with a valid identifier such as markdown:

const plugin = {
    configs: {},
    rules: {},
    processors: {

        // works in both old and new config systems
        "markdown": {
            preprocess() {},
            postprocess() {}
        }
    }
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

In order to use this renamed processor, you’ll also need to manually specify it inside of a config, such as:

import example from "eslint-plugin-example";

export default [
    {
        plugins: {
            example
        },
        processor: "example/markdown"
    }
];
1
2
3
4
5
6
7
8
9
10

You should update your plugin’s documentation to advise your users if you have renamed a file extension-named processor.

Migrating Configs for Flat Config

If your plugin is exporting configs that refer back to your plugin, then you’ll need to update your configs to flat config format. As part of the migration, you’ll need to reference your plugin directly in the plugins key. For example, here is an exported config in the old configuration system format for a plugin named eslint-plugin-example:

// plugin name: eslint-plugin-example
module.exports = {
    configs: {

        // the config referenced by example/recommended
        recommended: {
            plugins: ["example"],
            rules: {
                "example/rule1": "error",
                "example/rule2": "error"
            }
        }
    },
    rules: {
        rule1: {},
        rule2: {};
    }
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

To migrate to flat config format, you’ll need to move the configs to after the definition of the plugin variable in the recommended plugin structure, like this:

const plugin = {
    configs: {},
    rules: {},
    processors: {}
};

// assign configs here so we can reference `plugin`
Object.assign(plugin.configs, {
    recommended: {
        plugins: {
            example: plugin
        },
        rules: {
            "example/rule1": "error",
            "example/rule2": "error"
        }
    }
})

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Your users can then use this exported config like this:

import example from "eslint-plugin-example";

export default [

    // use recommended config
    example.configs.recommended,

    // and provide your own overrides
    {
        rules: {
            "example/rule1": "warn"
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14

If your config extends other configs, you can export an array:

const baseConfig = require("./base-config");

module.exports = {
    configs: {
        extendedConfig: [
            baseConfig,
            {
                rules: {
                    "example/rule1": "error",
                    "example/rule2": "error"
                }
            }
        ],
    },
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

You should update your documentation so your plugin users know how to reference the exported configs.

If your exported config is an object, then your users can insert it directly into the config array; if your exported config is an array, then your users should use the spread operator (...) to insert the array’s items into the config array.

Here’s an example with both an object config and an array config:

import example from "eslint-plugin-example";

export default [
    example.configs.recommended, // Object, so don't spread
    ...example.configs.extendedConfig, // Array, so needs spreading
];
1
2
3
4
5
6

For more information, see the full documentation.

Migrating Environments for Flat Config

Environments are no longer supported in flat config, and so we recommend transitioning your environments into exported configs. For example, suppose you export a mocha environment like this:

// plugin name: eslint-plugin-example
module.exports = {
    environments: {
        mocha: {
            globals: {
                it: true,
                xit: true,
                describe: true,
                xdescribe: true
            }
        }
    },
    rules: {
        rule1: {},
        rule2: {};
    }
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

To migrate this environment into a config, you need to add a new key in the plugin.configs object that has a flat config object containing the same information, like this:

const plugin = {
    configs: {},
    rules: {},
    processors: {}
};

// assign configs here so we can reference `plugin`
Object.assign(plugin.configs, {
    mocha: {
        languageOptions: {
            globals: {
                it: "writeable",
                xit: "writeable",
                describe: "writeable",
                xdescribe: "writeable"
            }
        }
    }
})

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25