Установка и настройка @typescript-eslint/parser

В стандартной конфигурации ESLint анализирует JavaScript-код с помощью встроенного парсера Espree. При работе с TypeScript такой подход становится ограничением, поскольку синтаксис TypeScript включает конструкции, отсутствующие в чистом Jav * aScript: типы, интерфейсы, перечисления, generics и модификаторы доступа.

Пакет @typescript-eslint/parser решает эту проблему, обеспечивая корректное преобразование TypeScript-кода в AST (Abstract Syntax Tree), понятное ESLint. Это позволяет применять правила линтинга к проектам, использующим TypeScript, без потери информации о типах и специфичных конструкциях языка.

Установка необходимых пакетов

Для корректной работы ESLint с TypeScript требуется несколько зависимостей:

  • ESLint как базовый линтер
  • TypeScript для компиляции и анализа типов
  • @typescript-eslint/parser как парсер
  • @typescript-eslint/eslint-plugin для набора правил, учитывающих TypeScript

Установка через npm:

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

При использовании pnpm:

pnpm add -D eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin

При использовании yarn:

yarn add -D eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin

Базовая настройка ESLint с TypeScript-парсером

Конфигурация ESLint традиционно задаётся через файл .eslintrc.* или через новый формат flat config (eslint.config.js).

Классическая конфигурация (.eslintrc)

{
  "parser": "@typescript-eslint/parser",
  "plugins": ["@typescript-eslint"],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended"
  ]
}

В данной конфигурации:

  • parser заменяет стандартный парсер ESLint на TypeScript-совместимый
  • plugins подключает набор TypeScript-правил
  • extends добавляет базовые и рекомендованные правила

Настройка parserOptions

Ключевая часть конфигурации — блок parserOptions, который определяет, как именно анализируется TypeScript-код.

Пример базовой конфигурации

{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2022,
    "sourceType": "module"
  }
}

Подключение TypeScript-проекта

Для включения правил, использующих информацию о типах, необходимо указать tsconfig.json:

{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "project": "./tsconfig.json",
    "tsconfigRootDir": "./",
    "sourceType": "module"
  }
}

Значение параметров

  • project Указывает путь к tsconfig.json. Включает type-aware linting, позволяющий анализировать типы, а не только синтаксис.

  • tsconfigRootDir Определяет корневую директорию для поиска конфигурации TypeScript. Особенно важно в монорепозиториях.

  • ecmaVersion Указывает версию ECMAScript, влияющую на поддержку синтаксиса JavaScript.

  • sourceType Обычно устанавливается в "module" для поддержки ES Modules.

Type-aware linting и его особенности

При использовании параметра project ESLint начинает выполнять полноценный анализ TypeScript через Program API компилятора.

Это включает:

  • анализ типов переменных и выражений
  • проверку совместимости типов в правилах
  • возможность использования правил, зависящих от TypeScript Compiler API

Последствия включения type-aware режима

Использование режима с project влияет на производительность:

  • увеличивается время запуска ESLint
  • требуется предварительная компиляция проекта TypeScript
  • возможны задержки при больших кодовых базах

Поэтому в некоторых случаях используется разделение конфигураций:

  • базовый линтинг без типов
  • расширенный линтинг для CI или pre-commit

Flat config (eslint.config.js)

Современный формат конфигурации ESLint использует JavaScript-модуль вместо JSON.

Пример настройки

import tsParser from "@typescript-eslint/parser";
import tsPlugin from "@typescript-eslint/eslint-plugin";

export default [
  {
    files: ["**/*.ts"],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        ecmaVersion: 2022,
        sourceType: "module",
        project: "./tsconfig.json",
        tsconfigRootDir: import.meta.dirname
      }
    },
    plugins: {
      "@typescript-eslint": tsPlugin
    },
    rules: {
      ...tsPlugin.configs.recommended.rules
    }
  }
];

Интеграция с monorepo

В монорепозиториях часто используется несколько tsconfig.json для разных пакетов. В этом случае требуется корректная настройка parserOptions.project.

Пример структуры:

packages/
  core/
    tsconfig.json
  ui/
    tsconfig.json

Конфигурация ESLint:

{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "project": [
      "./packages/core/tsconfig.json",
      "./packages/ui/tsconfig.json"
    ],
    "tsconfigRootDir": "./"
  }
}

В сложных проектах используется tsconfig.eslint.json, объединяющий все файлы, чтобы ускорить анализ.

Частые ошибки при настройке

ESLint не находит tsconfig.json

Причина обычно связана с неверным tsconfigRootDir.

Корректный вариант:

{
  "parserOptions": {
    "project": "./tsconfig.json",
    "tsconfigRootDir": "./"
  }
}

Ошибка Parsing error: Cannot read file

Возникает при:

  • неправильном пути к TypeScript проекту
  • отсутствии компиляции зависимостей
  • несовместимых версиях TypeScript и @typescript-eslint/parser

Правила не работают

Частая причина — подключён только parser без plugin:

{
  "plugins": ["@typescript-eslint"]
}

Без плагина правила TypeScript не активируются.

Рекомендованная структура конфигурации

Практически применимая конфигурация:

{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module",
    "project": "./tsconfig.eslint.json",
    "tsconfigRootDir": "./"
  },
  "plugins": ["@typescript-eslint"],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended-type-checked"
  ]
}

Режимы конфигурации ruleset

@typescript-eslint предоставляет несколько уровней наборов правил:

  • recommended — базовый набор без анализа типов
  • recommended-type-checked — расширенный набор с type-aware анализом
  • strict — максимально строгие правила
  • strict-type-checked — строгие правила с использованием типов

Использование более строгих наборов увеличивает точность анализа, но повышает стоимость проверки проекта.

Влияние версии TypeScript

Совместимость parser зависит от версии TypeScript. При обновлении возможны изменения в:

  • AST структуре
  • поддержке новых синтаксических конструкций
  • поведении type-aware анализа

Рекомендуется синхронизировать версии:

  • TypeScript
  • @typescript-eslint/parser
  • @typescript-eslint/eslint-plugin

Несовместимость версий приводит к ошибкам парсинга или некорректной работе правил.

Оптимизация производительности

Для больших проектов применяются следующие подходы:

  • выделение отдельного tsconfig.eslint.json
  • исключение test-файлов из type-aware анализа
  • использование files в flat config
  • ограничение scope через parserOptions.project

Пример облегчённого tsconfig:

{
  "extends": "./tsconfig.json",
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist", "tests"]
}

Связка с редакторами и CI

В редакторах (VS Code, WebStorm) парсер используется через ESLint integration, поэтому корректность parserOptions критична для одинакового поведения в:

  • локальной разработке
  • CI пайплайнах
  • pre-commit хуках

Расхождение конфигураций приводит к ситуации, когда ошибки видны только в одной среде, что усложняет отладку.

Оглавление