Переносим Angular проект на ESLint, с Prettier, Husky и lint-staged

  • Tutorial
Привет, Хабр! Меня зовут Богдан, я работаю в ПИК Digital Front-End тимлидом. Большую часть проектов мы разрабатываем на Angular и недавно я решил пересмотреть наши стайл гайды, а также добавить новые инструменты для более удобной работы.

В качестве линтера я решил использовать ESLint, так как в скором времени на него планируют перевести Angular. И в этой статье я хочу поделиться инструкцией по переходу с TSLint на ESLint, а заодно рассказать, как запускать Prettier из ESLint, как добавить правила стайл гайда AirBnB, и как сделать линтинг удобным и незаметным с помощью настройки VS Code и Git хуков.

Prettier & ESLint


ESLint — это инструмент для статического анализа кода, правила в нём делятся на две группы:

  • Форматирование — для приведения кода в один вид: длина строк, запятые, точки с запятой и тд.
  • Качество кода — поиск проблемных шаблонов кода: ненужный код, ошибки.

Prettier — это инструмент автоматического форматирования кода.

Вопрос, который меня интересовал: зачем использовать Prettier, если ESLint тоже умеет форматировать код?

Ответ простой — Prettier форматирует код намного лучше: убирает всё форматирование и полностью переписывает код в едином стиле. Это позволяет разработчикам забыть о форматировании кода и не тратить время на обсуждение стиля кода на ревью. Например, у нас есть длинная строчка кода:

image

Если мы попробуем изменить форматирование через ESLint, он просто выдаст нам ошибку:

eslint example.ts --fix

output:
error    This line has a length of 97. Maximum allowed is 80

Такой пример показывает, что линтеры не всегда могут помочь с форматированием кода, а разработчики могут отформатировать этот код по-разному, исходя из своих личных соображений.

Если же мы сохраним или форматируем файл с Prettier, то строка примет вид:

image

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

Настройка ESLint


Суть линтинга с помощью ESLint заключается в парсерах, которые трансформируют код в AST (Abstract Syntax Tree) для дальнейшей программной обработки, и плагинах, которые содержат правила, например, рекомендуемые правила для линтинга TypeScript или правила код гайда AirBnB.

Установка


Для миграции Angular приложения на ESLint нам потребуются следующие зависимости:

  • eslint — сам линтер,
  • @angular-eslint/builder — Angular CLI Builder для запуска ESLint для приложений на Angular с помощью стандартной команды ng lint,
  • @angular-eslint/eslint-plugin — плагин, содержащий правила для линтинга Angular,
  • @angular-eslint/template-parser — парсер, который с помощью angular/compiler делает возможным написание правил для линтинга Angular шаблонов,
  • @angular-eslint/eslint-plugin-template — плагин, который при использовании вместе с @angular-eslint/template-parser, запускает правила для линтинга Angular шаблонов,
  • @typescript-eslint/parser — плагин для парсинга TypeScript кода,
  • @typescript-eslint/eslint-plugin — плагин, который запускает правила для линтинга TypeScript.

Для их установки достаточно запустить команду:

ng add @angular-eslint/schematics

На момент написания статьи в typescript-eslint и angular-eslint реализованы не все эквиваленты для правил из стандартной конфигурации Сodelyzer для TSLint, но большая часть уже есть. Отслеживать актуальное состояние переноса правил из TSLint в ESLint вы можете в монорепозиториях Angular ESLint и TypeScript ESLint.

Настройка конфига


Всё, что нам надо для линтинга Angular приложения, мы установили. Теперь перейдём к настройке ESLint. Давайте создадим файл .eslintrc.js и добавим рекомендованные настройки для Angular ESLint:

module.exports = {
  extends: ['plugin:@angular-eslint/recommended'],
  rules: {
    '@angular-eslint/directive-selector': [
      'error',
      { type: 'attribute', prefix: 'app', style: 'camelCase' },
    ],
    '@angular-eslint/component-selector': [
      'error',
      { type: 'element', prefix: 'app', style: 'kebab-case' },
    ],
  },
  overrides: [
    // Добавьте эти настройки, если вы задаёте шаблоны внутри файлов *.component.ts
    {
      files: ['*.component.ts'],
      parser: '@typescript-eslint/parser',
      parserOptions: {
        ecmaVersion: 2020,
        sourceType: 'module',
      },
      plugins: ['@angular-eslint/template'],
      processor: '@angular-eslint/template/extract-inline-html',
    },
  ],
};

Конфиги можно описывать в разных форматах: JavaScript, JSON или YAML file. В JavaScript можно оставлять комментарии.

«plugin:@angular-eslint/recommended» содержит настройки сразу для 3 плагинов: "@typescript-eslint/eslint-plugin", "@angular-eslint/eslint-plugin" и "@angular-eslint/eslint-plugin-template". Прочитать, какие правила он задаёт, можно тут.

Обновление команды ng lint


Также в конфигурации angular.json нужно обновить команду ng lint на запуск @angular-eslint/builder:

"lint": {
  "builder": "@angular-eslint/builder:lint",
  "options": {
    "eslintConfig": ".eslintrc.js",
    "tsConfig": [
      "tsconfig.app.json",
      "tsconfig.spec.json",
      "e2e/tsconfig.json"
    ],
    "exclude": [
      "**/node_modules/**"
    ]
  }
},

Базовая настройка ESLint готова, теперь запустить ESLint можно стандартной командой ng lint.

Установка дополнительных плагинов


Чтобы установить плагин для ESLint, например, для линтинга unit-тестов в Angular, надо скачать и добавить в настройки плагин Jasmine:

npm install eslint-plugin-jasmine --save-dev

И добавить в свойство «overrides» новый блок настроек для файлов с расширением *.spec.ts:

overrides: [
  ...,
  {
    files: ['src/**/*.spec.ts', 'src/**/*.d.ts'],
    parserOptions: {
      project: './src/tsconfig.spec.json',
    },
    // Правила для линтера
    extends: ['plugin:jasmine/recommended'],
    // Плагин для запуска правил
    plugins: ['jasmine'],
    env: { jasmine: true },
    // Отключим правило 'no-unused-vars'
    rules: {
      '@typescript-eslint/no-unused-vars': 'off',
    },
  }
],

По аналогии вы можете добавить другие плагины для разных расширений файлов.

Добавляем правила стайл гайдов


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

  • AirBnB: самый популярный и строгий из этих трёх, обязательные замыкающие запятые и точки с запятыми.
  • Google: похож на AirBnB в плане форматирования, но менее строгий, обязательные комментарии JSDoc.
  • StandartJS: запрещает использовать замыкающие запятые и точки с запятыми.

Выбирайте стайл гайд, который больше подходит вашей команде. Можете поочередно попробовать все стайл гайды на каком-нибудь большом проекте, посмотреть, какие ошибки выдаёт линтер и на основании этого сделать выбор.

Выбирайте реализацию стайл гайда на TypeScript, потому что правила для JavaScript могут неправильно отрабатывать на TypeScript.

В качестве примера, добавим в наш конфиг ESLint правила стайл гайда AirBnB. Для этого установим конфиг с правилами AirBnB для TypeScript и плагин с правилами для работы с синтаксисом import/export:

npm install eslint-plugin-import eslint-config-airbnb-typescript --save-dev

Чтобы не изменять верхнеуровневые настройки, создадим новый блок правил в свойстве «overrides» с правилами стайл гайда AirBnB, и необходимым для их работы парсером TypeScript:

module.exports = {
  ...,
  overrides: [
    ...,
    {
      files: ['*.ts'],
      extends: [
        'airbnb-typescript/base',
      ],
      parser: '@typescript-eslint/parser',
      parserOptions: {
        ecmaVersion: 2020,
        sourceType: 'module',
      },
    },
  ]
}

Чтобы добавить другой стайл гайд, нужно установить набор правил для TypeScript, создать новый блок правил в «overrides» с правилами стайл гайда и указать необходимый для их работы парсер.

Кастомизация правил


Если вы хотите отключить или переопределить какие-то правила стайл гайда, то это можно сделать в свойстве «rules»:

module.exports = {
  ...,
  overrides: [
    ...,
    {
      files: ['*.ts'],
      extends: [
        'airbnb-typescript/base',
      ],
      parser: '@typescript-eslint/parser',
      parserOptions: {
        ecmaVersion: 2020,
        sourceType: 'module',
      },
      // Кастомные правила
      rules: {
        'import/no-unresolved': 'off',
        'import/prefer-default-export': 'off',
        'class-methods-use-this': 'off',
        'lines-between-class-members': 'off',
        '@typescript-eslint/unbound-method': [
          'error',
          {
            ignoreStatic: true,
          },
        ],
      },
    },
  ]
}


Настройка Prettier


Чтобы добавить Prettier в нашу конфигурацию, нам надо установить сам Prettier, плагин с правилами Prettier, а также конфиг, который отключит все правила, которые могут конфликтовать с Prettier:

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

В «overrides» в блоке с правилами файлов с расширением *.ts в свойство «extends» в самый низ добавьте правила и настройки Prettier:

module.exports = {
  ...,
  overrides: [
    ...,
    {
      files: ['*.ts'],
      extends: [
        // Стайл гайд AirBnB
	'airbnb-typescript/base',
	// Настройки для Prettier
	'prettier/@typescript-eslint',
	'plugin:prettier/recommended',
      ],
      ...,
    },
  ]
}

Конфигурация для Prettier всегда должна быть в самом низу списка, чтобы перезаписать все правила, которые могут конфликтовать с Prettier.

`prettier/@typescript-eslint` отключает правила `@typescript-eslint`, которые могут конфликтовать с Prettier, а `plugin:prettier/recommended` делает три вещи:

  • включает eslint-plugin-prettier,
  • выводит в консоль ошибки правил prettier/prettier как  «error»,
  • добавляет правила форматирования Prettier eslint-config-prettier.

Конфиг для Prettier:


Prettier умеет форматировать код без всяких настроек, но для соответствия стайл гайду AirBnB необходимо добавить некоторые настройки. Создайте файл .prettierrc.js в корне приложения:

module.exports = {
  trailingComma: "all",
  tabWidth: 2,
  semi: true,
  singleQuote: true,
  bracketSpacing: true,
  printWidth: 100
};

Эти настройки будут использоваться как ESLint, так и Prettier, если вы будете использовать его для форматирования файлов в VS Code или с помощью команды:

prettier "--write ."

Настройка VS Code


VS Code может подсвечивать и исправлять при сохранении ошибки найденные ESLint. Для этого надо скачать плагин ESLint для VS Code и создать файл внутри проекта с настройками для рабочей области .vscode/settings.json:

  "eslint.validate": [ "javascript", "typescript", "html"],

  "eslint.options": {
    "extensions": [".js", ".ts", "html"]
  },

  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
  },

Здесь мы настраиваем ESLint, чтобы он подчёркивал и исправлял ошибки при сохранения файлов с расширениями .js, .ts и .html.

А чтобы форматировать документ комбинацией клавиш «shift+option+F» или «shift+alt+F» скачайте плагин Prettier для VS Code, и установите его как форматировщик по умолчанию.

Настройка Git хуков


Git хуки — это скрипты, которые Git вызывает при определённых событиях: commit, push, recieve.

С помощью них, мы можем запускать линтинг кода при создании коммита, чтобы в пул реквесты попадало меньше ошибок. Для более удобной работы с Git хуками установим Husky, а чтобы проверять только тот код, который добавлен в коммит (это полезно в больших проектах, где линтинг занимает много времени) lint-staged:

npm i husky lint-staged --save-dev

Добавим настройки для этих плагинов в package.json:

"scripts": {
  ...
},
"husky": {
  "hooks": {
    "pre-commit": "lint-staged --relative"
  }
},
"lint-staged": {
  "*.{js,ts}": [
     "eslint --fix"
  ]
},

lint-staged передаёт в вызываемую команду массив изменённых файлов. Команда ng lint не умеет принимать массив файлов, и для её использования надо писать дополнительный скрипт-обработчик. А можно просто вызвать ESLint, как в этом примере. Такое решение можно использовать для прекоммитов, а ng lint запускать для линтинга всего проекта, например в CI пайплайне.

Выводы


В будущих версиях Angular ESLint с базовыми правилами будет из коробки. Сейчас процесс настройки ESLint требует некоторых дополнительных действий, в ESLint нет эквивалентов для некоторых правил из TSLint, и Angular ESLint ещё находится в alpha-версии. Поэтому переходить сейчас на ESLint или нет — решать вам.

Однако код гайды, дополнительные правила, Prettier, Husky и lint-staged вам придётся настраивать самостоятельно. Надеюсь эта статья помогла вам разобраться как все эти вещи работают вместе.

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

Но время, затраченное на настройку линтеров, в будущем значительно сэкономит вам время на обсуждение стиля и форматирования кода в процессе код ревью, сократит количество ошибок, попадающих в пул реквесты, и обеспечит консистентность кодовой базы.

Пример реализации можно посмотреть на Github.

Если вы нашли ошибку в конфиге, или у вас есть дополнения — пишите!

Ссылки


AdBlock похитил этот баннер, но баннеры не зубы — отрастут

Подробнее
Реклама

Комментарии 5

    0

    Круто, что в 2020 вы решились на такой серьезный шаг.
    И компиляция множества туториалов и документации будет многим полезна.


    Но, лично мне, было бы стыдно писать о такой банальщине на хабре.

      +5
      Ага. Многие так думают и ничего не пишут. А потом нигде никакой информации собранной в одном месте сразу не найдешь. Это же легко, делается все очень просто, банальщина и т.п.
        –2

        Как раз на эту тему информации вагон и маленькая тележка.


        Если быть было «вся информация в одном месте» — это было бы актуально :)
        С разбром проблем, багов. С рассмотрением разных IDE (atom, idea).


        А так, только под один фреймворк, да ещё и без указания версий. Без исходников.


        Это уровень medium.com. И, кстати, там полно подобных статей.

          +1
          Вот точно такая же статья на первой странице хаба Angular:

          image

          Ключевые слова те же «eslint», «prettier», «husky», «lint-staged». Зачем писать ещё одну?
            0
            Там нет инструкции по миграции на ESLint.
            image

      Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

      Самое читаемое