Создание плагинов

Плагины ESLint расширяют функциональность ESLint дополнительными возможностями. В большинстве случаев вы будете расширять ESLint, создавая плагины, которые инкапсулируют дополнительную функциональность, которую вы хотите использовать в нескольких проектах.

Создание плагина

Плагин — это объект JavaScript, который предоставляет определённые свойства ESLint:

• meta — информация о плагине.
• configs — объект, содержащий именованные конфигурации.
• rules — объект, содержащий определения пользовательских правил.
• processors — объект, содержащий именованные обработчики.

Для начала создайте файл JavaScript и экспортируйте объект, содержащий свойства, которые вы хотите использовать в ESLint. Чтобы ваш плагин был максимально простым в обслуживании, рекомендуем форматировать ваш файл точки входа плагина следующим образом:

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

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;

Если вы планируете распространять свой плагин как пакет npm, убедитесь, что модуль, экспортирующий объект плагина, является стандартным экспортом вашего пакета. Это позволит ESLint импортировать плагин при указании его в командной строке в опции --plugin.

Метаданные в плагинах

Для более простого отладки и эффективного кеширования плагинов рекомендуется указывать имя и версию в объекте meta в корне вашего плагина, например:

const plugin = {

    // preferred location of name and version
    meta: {
        name: "eslint-plugin-example",
        version: "1.2.3"
    },
    rules: {
        // add rules here
    }
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;

Свойство meta.name должно совпадать с именем пакета npm для вашего плагина, а свойство meta.version должно совпадать с версией пакета npm для вашего плагина. Самый простой способ сделать это — считать эту информацию из вашего package.json, как в этом примере:

import fs from "fs";

const pkg = JSON.parse(fs.readFileSync(new URL("./package.json", import.meta.url), "utf8"));

const plugin = {

    // preferred location of name and version
    meta: {
        name: pkg.name,
        version: pkg.version
    },
    rules: {
        // add rules here
    }
};

export default plugin;

В качестве альтернативы вы также можете экспортировать свойства name и version в корне вашего плагина, например:

const plugin = {

    // alternate location of name and version
    name: "eslint-plugin-example",
    version: "1.2.3",
    rules: {
        // add rules here
    }
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;

Правила в плагинах

Плагины могут предоставлять пользовательские правила для использования в ESLint. Для этого плагин должен экспортировать объект rules, содержащий сопоставление идентификатора правила с самим правилом. Идентификатор правила не должен соответствовать никаким соглашениям об именовании, за исключением того, что он не должен содержать символ / (например, может быть dollar-sign, но не foo/dollar-sign). Чтобы узнать больше о создании пользовательских правил в плагинах, обратитесь к разделу Пользовательские правила.

const plugin = {
    meta: {
        name: "eslint-plugin-example",
        version: "1.2.3"
    },
    rules: {
        "dollar-sign": {
            create(context) {
                // rule implementation ...
            }
        }
    }
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;

Чтобы использовать правило из плагина в файле конфигурации, импортируйте плагин и включите его в ключ plugins, указав пространство имён. Затем используйте это пространство имён для ссылки на правило в конфигурации rules, как в этом примере:

// eslint.config.js
import example from "eslint-plugin-example";

export default [
    {
        plugins: {
            example
        },
        rules: {
            "example/dollar-sign": "error"
        }
    }
];

Обработчики в плагинах

Плагины могут экспортировать обработчики для использования в файле конфигурации, предоставив объект processors. Подобно правилам, каждый ключ в объекте processors — это имя обработчика, а каждое значение — сам объект обработчика. Вот пример:

const plugin = {
    meta: {
        name: "eslint-plugin-example",
        version: "1.2.3"
    },
    processors: {
        "processor-name": {
            preprocess(text, filename) {/* ... */},
            postprocess(messages, filename) { /* ... */ },
        }
    }
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;

Чтобы использовать обработчик из плагина в файле конфигурации, импортируйте плагин и включите его в ключ plugins, указав пространство имён. Затем используйте это пространство имён для ссылки на обработчик в конфигурации processor, как в этом примере:

// eslint.config.js
import example from "eslint-plugin-example";

export default [
    {
        plugins: {
            example
        },
        processor: "example/processor-name"
    }
];

Конфигурации в плагинах

Вы можете объединять конфигурации внутри плагина, указав их под ключом configs. Это может быть полезно, когда вы хотите объединить набор пользовательских правил с конфигурацией, которая включает рекомендуемые параметры. Поддерживается несколько конфигураций на плагин.

Вы можете включать отдельные правила из плагина в конфигурацию, которая также включена в плагин. В конфигурации необходимо указать имя вашего плагина в объекте plugins и любые правила, которые вы хотите включить и которые являются частью плагина. Все правила плагина должны иметь префикс из пространства имён плагина. Вот пример:

const plugin = {
    meta: {
        name: "eslint-plugin-example",
        version: "1.2.3"
    },
    configs: {},
    rules: {
        "dollar-sign": {
            create(context) {
                // rule implementation ...
            }
        }
    }
};

// assign configs here so we can reference `plugin`
Object.assign(plugin.configs, {
    recommended: [{
        plugins: {
            example: plugin
        },
        rules: {
            "example/dollar-sign": "error"
        },
        languageOptions: {
            globals: {
                myGlobal: "readonly"
            },
            parserOptions: {
                ecmaFeatures: {
                    jsx: true
                }
            }
        }
    }]
});

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;

Этот плагин экспортирует конфигурацию recommended, которая представляет собой массив с одним объектом конфигурации. Когда есть только один объект конфигурации, вы также можете экспортировать только объект без окружающего массива.

Чтобы использовать конфигурацию из плагина в файле конфигурации, импортируйте плагин и напрямую обратитесь к конфигурации через объект плагина. Предполагая, что конфигурация является массивом, используйте оператор spread, чтобы добавить её в массив, возвращаемый файлом конфигурации, как в этом примере:

// eslint.config.js
import example from "eslint-plugin-example";

export default [
    ...example.configs.recommended
];

Тестирование плагина

ESLint предоставляет утилиту RuleTester для простого тестирования правил вашего плагина.

Проверка плагина на соответствие стилю

Плагины ESLint также должны проверяться на соответствие стилю! Рекомендуется проверять свой плагин с помощью конфигураций recommended:

• eslint
• eslint-plugin-eslint-plugin
• eslint-plugin-n

Распространение плагинов

Чтобы сделать ваш плагин доступным публично, необходимо опубликовать его в npm. При этом, пожалуйста, убедитесь, что:

1. Укажите ESLint как зависимость peer. Поскольку плагины предназначены для использования с ESLint, важно добавить пакет eslint в качестве peer-зависимости. Для этого вручную отредактируйте файл package.json и добавьте блок peerDependencies, как в этом примере:

   {
       "peerDependencies": {
           "eslint": ">=9.0.0"
       }
   }
   

2. Укажите ключевые слова. Плагины ESLint должны указывать eslint, eslintplugin и eslint-plugin в качестве ключевых слов в файле package.json.