Plugin 遷移至扁平化配置

從 ESLint v9.0.0 開始，預設的設定系統將會是新的扁平化配置系統。為了讓您的插件能夠與扁平化設定檔一起運作，您需要對現有的插件進行一些變更。

建議的插件結構

為了讓您的插件在扁平化配置系統中更容易運作，建議您將現有的插件入口點切換成如下所示

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

這種結構在進行本頁討論的其他變更時，能提供最大的彈性。

新增插件 Meta 資訊

在舊的 eslintrc 設定系統中，ESLint 可以從套件名稱中提取有關插件的資訊，但在扁平化配置中，ESLint 無法再存取插件套件的名稱。為了取代遺失的資訊，您應該新增一個包含至少 name 鍵的 meta 鍵，理想情況下，還應包含 version 鍵，例如

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

如果您的插件是以 npm 套件形式發佈，則 name 和 version 應與您的 package.json 檔案中的相同；否則，您可以指定任何您想要的值。

如果沒有此 meta 資訊，您的插件將無法與 --cache 和 --print-config 命令列選項一起使用。

遷移扁平化配置的規則

您的插件中的 rules 鍵不需要進行任何變更。一切都與舊的 eslintrc 設定系統相同。

遷移扁平化配置的處理器

每個處理器都應指定一個 meta 物件。如需更多資訊，請參閱完整文件。

只要您未使用檔案副檔名命名的處理器，插件中的 processors 鍵就不需要進行其他變更。如果您有任何檔案副檔名命名的處理器，您必須將名稱更新為有效的識別符（數字和字母）。檔案副檔名命名的處理器在舊的設定系統中會自動套用，但在使用扁平化配置時不會自動套用。以下是檔案副檔名命名的處理器範例

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

名稱 ".md" 對於處理器而言已不再有效，因此必須替換為有效的識別符，例如 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

為了使用這個重新命名的處理器，您還需要在設定中手動指定它，例如

import example from "eslint-plugin-example";

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

如果您已重新命名檔案副檔名命名的處理器，您應該更新插件的文件，以告知您的使用者。

遷移扁平化配置的設定

如果您的插件正在匯出會回指您的插件的設定，那麼您需要將您的設定更新為扁平化配置格式。作為遷移的一部分，您需要在 plugins 鍵中直接參考您的插件。例如，以下是名為 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

若要遷移至扁平化配置格式，您需要將設定移至建議的插件結構中 plugin 變數定義之後，如下所示

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

然後您的使用者可以像這樣使用此匯出的設定

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

如果您的設定擴展了其他設定，您可以匯出一個陣列

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

您應該更新您的文件，以便您的插件使用者知道如何參考匯出的設定。

如果您的匯出設定是一個物件，那麼您的使用者可以直接將其插入設定陣列中；如果您的匯出設定是一個陣列，那麼您的使用者應該使用展開運算符 (...) 將陣列的項目插入設定陣列中。

以下是一個同時包含物件設定和陣列設定的範例

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

如需更多資訊，請參閱完整文件。

遷移扁平化配置的環境

扁平化配置不再支援環境，因此我們建議將您的環境轉換為匯出的設定。例如，假設您匯出一個如下所示的 mocha 環境

// 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

若要將此環境遷移至設定，您需要在 plugin.configs 物件中新增一個鍵，該鍵具有包含相同資訊的扁平化設定物件，如下所示

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

然後您的使用者可以像這樣使用此匯出的設定

import example from "eslint-plugin-example";

export default [

    // use the mocha globals
    example.configs.mocha,

    // and provide your own overrides
    {
        languageOptions: {
            globals: {
                it: "readonly"
            }
        }
    }
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

您應該更新您的文件，以便您的插件使用者知道如何參考匯出的設定。

向後相容性

如果您的插件需要同時適用於舊的和新的設定系統，那麼您需要

匯出 CommonJS 入口點。 舊的設定系統無法載入僅以 ESM 格式發佈的插件。如果您的原始碼是 ESM 格式，那麼您需要使用一個可以產生 CommonJS 版本的 bundler，並使用您 package.json 檔案中的 exports 鍵，以確保 Node.js 可以找到 CommonJS 版本。
保留 environments 鍵。 如果您的插件匯出自訂環境，您應該保持這些環境不變，並同時匯出如上所述的等效扁平化配置。當 ESLint 在扁平化配置模式下執行時，environments 鍵會被忽略。
同時匯出 eslintrc 和扁平化配置。 configs 鍵僅在設定檔被使用時才會驗證，因此您可以在 configs 鍵中提供兩種格式的設定檔。我們建議您在舊格式的設定檔後附加 -legacy，以清楚表明這些設定檔在未來將不再受支援。例如，如果您的主要設定檔名為 recommended 且為扁平化配置格式，那麼您也可以有一個名為 recommended-legacy 的設定檔，它是 eslintrc 設定檔格式。

延伸閱讀

編輯此頁面