ESLint + TypeScript плагины TypeScript: методы, примеры…

Введение: Что такое ESLint + TypeScript плагины и зачем они нужны?

В современной веб-разработке TypeScript стал стандартом де-факто для создания масштабируемых и надежных приложений. Однако даже самый строгий компилятор TypeScript не может уловить все логические ошибки, стилистические несоответствия или потенциальные баги, которые могут возникнуть в процессе написания кода. Здесь на помощь приходит ESLint — мощный линтер для JavaScript, который с помощью специальных плагинов адаптируется для работы с TypeScript.

ESLint + TypeScript плагины — это не отдельная библиотека в привычном понимании (как, например, Lodash), а скорее экосистема инструментов. Основной пакет — eslint — отвечает за анализ кода, а плагины @typescript-eslint/eslint-plugin и @typescript-eslint/parser добавляют поддержку синтаксиса TypeScript и предоставляют сотни правил, специфичных для TypeScript.

Зачем это нужно?

Поиск ошибок на ранних этапах: Линтер может обнаружить потенциальные проблемы, которые компилятор TypeScript пропустит (например, неиспользуемые переменные, неправильное использование промисов, проблемы с типами, которые не являются синтаксическими).
Единый стиль кода: В команде разработчиков линтер обеспечивает соблюдение единого код-стайла (отступы, кавычки, точки с запятой), что делает код более читаемым и предсказуемым.
Автоматическое исправление: Многие правила ESLint поддерживают автоисправление (--fix), что позволяет автоматически форматировать код и исправлять простые ошибки.
Интеграция с IDE: Большинство современных редакторов кода (VS Code, WebStorm) имеют встроенную поддержку ESLint, что позволяет видеть ошибки и предупреждения прямо во время написания кода.

На сайте pythonlib.ru мы стремимся предоставлять максимально полезные руководства. Эта статья станет вашим исчерпывающим справочником по настройке и использованию ESLint с TypeScript.

Установка ESLint и TypeScript плагинов

Установка производится через менеджер пакетов npm (или yarn, pnpm). Предполагается, что у вас уже есть проект с файлом package.json и установлен TypeScript (typescript).

Выполните в терминале в корне вашего проекта:

npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

Разберем, что мы установили:

eslint — ядро линтера.
@typescript-eslint/parser — парсер, который позволяет ESLint понимать синтаксис TypeScript (включая дженерики, декораторы, типы и т.д.).
@typescript-eslint/eslint-plugin — плагин, который содержит набор правил, специфичных для TypeScript (например, @typescript-eslint/no-unused-vars вместо стандартного no-unused-vars).

Дополнительно (рекомендуется):

npm install --save-dev eslint-config-prettier eslint-plugin-prettier

Это позволит интегрировать ESLint с Prettier (форматтером кода) и избежать конфликтов между ними.

Быстрый старт: настройка и первый запуск

После установки необходимо создать конфигурационный файл. Самый простой способ — сгенерировать его с помощью встроенного в ESLint мастера:

npx eslint --init

Вас спросят несколько вопросов. Выберите:

Как вы хотите использовать ESLint? — To check syntax, find problems, and enforce code style
Какой модульный формат вы используете? — JavaScript modules (import/export)
Какой фреймворк? — None of these (или React/Vue/Angular, если используете)
Используете ли вы TypeScript? — Yes
Где запускается ваш код? — Browser (или Node, в зависимости от проекта)
Какой формат конфигурации? — JSON (или JavaScript, YAML — на ваш вкус)

После ответов будет создан файл .eslintrc.json (или .eslintrc.js). Он будет выглядеть примерно так:

{
    "env": {
        "browser": true,
        "es2021": true
    },
    "extends": [
        "eslint:recommended",
        "plugin:@typescript-eslint/recommended"
    ],
    "parser": "@typescript-eslint/parser",
    "parserOptions": {
        "ecmaVersion": "latest",
        "sourceType": "module"
    },
    "plugins": [
        "@typescript-eslint"
    ],
    "rules": {
        // Здесь можно переопределять правила
    }
}

Пример кода для проверки:

Создайте файл example.ts:

// example.ts
function greet(name: string): string {
    console.log("Hello, " + name);
    return `Hello, ${name}`;
}

let unusedVariable = 42; // ESLint укажет на это

greet("World");

Запуск линтера:

npx eslint example.ts

Вы увидите в терминале предупреждение о неиспользуемой переменной unusedVariable. Если вы хотите, чтобы линтер также автоматически исправлял то, что может (например, точки с запятой), используйте флаг --fix:

npx eslint example.ts --fix

Основные методы/функции (правила) ESLint + TypeScript плагинов

Вместо "методов" в классическом понимании, ESLint оперирует правилами. Каждое правило — это функция, которая анализирует AST (абстрактное синтаксическое дерево) кода и сообщает о нарушениях. Ниже приведены 10 наиболее важных и часто используемых правил из плагина @typescript-eslint.

1. `@typescript-eslint/no-unused-vars`

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

Параметры: Принимает объект с опциями, например { "argsIgnorePattern": "^_" } — игнорировать аргументы, начинающиеся с подчеркивания.

Пример:

// Плохо (ESLint выдаст ошибку)
const unusedVar = 10;

// Хорошо
const usedVar = 10;
console.log(usedVar);

// Игнорирование аргументов с подчеркиванием
function example(_unusedArg: string, usedArg: number) { // _unusedArg не вызовет ошибку
    console.log(usedArg);
}

2. `@typescript-eslint/explicit-function-return-type`

Что делает: Требует явно указывать возвращаемый тип для функций и методов. Это делает код более документированным и понятным.

Параметры: allowExpressions: true — разрешить не указывать тип для стрелочных функций, которые являются выражениями (например, const fn = () => 5).

Пример:

// Плохо (ESLint выдаст ошибку)
function add(a: number, b: number) {
    return a + b;
}

// Хорошо
function add(a: number, b: number): number {
    return a + b;
}

// С опцией allowExpressions: true
const multiply = (a: number, b: number) => a * b; // Ошибки не будет

3. `@typescript-eslint/no-explicit-any`

Что делает: Запрещает использовать тип any. any отключает всю систему типов TypeScript, что может привести к ошибкам. Рекомендуется использовать unknown или конкретные типы.

Параметры: fixToUnknown: true — автоматически заменять any на unknown при автоисправлении.

Пример:

// Плохо
function processData(data: any): void {
    console.log(data.name); // Нет гарантии, что у data есть поле name
}

// Хорошо (с использованием unknown и проверки)
function processDataSafe(data: unknown): void {
    if (typeof data === 'object' && data !== null && 'name' in data) {
        console.log((data as { name: string }).name);
    }
}

// Или с конкретным интерфейсом
interface Data {
    name: string;
}
function processDataBetter(data: Data): void {
    console.log(data.name);
}

4. `@typescript-eslint/no-non-null-assertion`

Что делает: Запрещает использование оператора ненулевого утверждения (!). Этот оператор говорит TypeScript "поверь мне, это значение не null/undefined", что может быть опасно, если вы ошибаетесь.

Параметры: Нет специфических параметров, только уровень ошибки (error/warn/off).

Пример:

// Плохо (ESLint выдаст ошибку)
const element = document.getElementById('myId')!;
element.innerHTML = 'Hello'; // Если элемента нет, будет ошибка в рантайме

// Хорошо (с проверкой)
const element = document.getElementById('myId');
if (element) {
    element.innerHTML = 'Hello';
}

5. `@typescript-eslint/ban-ts-comment`

Что делает: Запрещает или ограничивает использование комментариев @ts-ignore, @ts-expect-error, @ts-nocheck. Эти комментарии отключают проверку типов, что может скрыть реальные проблемы.

Параметры: ts-ignore: allow-with-description — разрешить @ts-ignore, но требовать описания причины.

Пример:

// Плохо (ESLint выдаст ошибку, если правило настроено на error)
// @ts-ignore
const result: string = someFunction(); // Мы не знаем, что возвращает someFunction

// Лучше (с описанием)
// @ts-expect-error: Эта функция временно возвращает any, пока не обновим типы
const result: string = someFunction();

// Идеально
const result: string = someFunction() as unknown as string; // Явное приведение

6. `@typescript-eslint/no-floating-promises`

Что делает: Запрещает "плавающие" промисы — то есть промисы, у которых не обработана ошибка (нет .catch() или await). Это предотвращает "проглатывание" ошибок в асинхронном коде.

Параметры: ignoreVoid: true — игнорировать промисы, переданные в void (например, void someAsyncFunction()).

Пример:

// Плохо (ESLint выдаст ошибку)
async function fetchData() {
    // ...
}
fetchData(); // Промис не обработан

// Хорошо
async function fetchData() {
    // ...
}
fetchData().catch(console.error); // Обработка ошибки

// Или с await
async function main() {
    await fetchData();
}