Общая конфигурация линтеров

Набор конфигурационных файлов для валидации react/node/typescript-проектов.

Как я могу внести изменения?

🚀 Миграция на версию 9/10 c 8

Установка и обновление

Установить библиотеку в проект нужно как dev dependency:

    yarn add -D arui-presets-lint

⚠️ С версии 8.0.0 библиотеке более не требуется установка peer dependency

Далее произвести следующие настройки:

Подключение конфигов prettier/stylelint/commitlint через package.json:

{
    "prettier": "arui-presets-lint/prettier",
    "stylelint": { "extends": "arui-presets-lint/stylelint" },
    "commitlint": { "extends": "arui-presets-lint/commitlint" }
}

Для настройки eslint нужно создать в корне проекта файл eslint.config.mts со следующим содержанием:

import { defineConfig, eslintConfig } from 'arui-presets-lint/eslint';

export default defineConfig(eslintConfig);

Если нужно расширить конфиг eslint на уровне проекта, дополнить его какими-то плагинами, можно это сделать подобным способом:

import pluginCypress from 'eslint-plugin-cypress';
import { defineConfig, eslintConfig, CYPRESS_SCOPE } from 'arui-presets-lint/eslint';

export default defineConfig(eslintConfig, [
    {
        rules: {
            'no-console': 'off',
            'max-lines': 'off',
        },
    },
    pluginCypress.configs.recommended,
    {
        files: [CYPRESS_SCOPE],
        rules: {
            'cypress/no-unnecessary-waiting': 'warn',
        },
    },
]);

Не забывайте про директиву files, её нужно указывать, если правило переопределяется (не выключается). Константы можно импортировать из arui-presets-lint, например:

import { defineConfig, eslintConfig, TYPESCRIPT_SCRIPTS_SCOPE } from 'arui-presets-lint/eslint'

export default defineConfig(eslintConfig, [
    {
        rules: {
            '@typescript-eslint/consistent-type-assertions': 'warning',
        }
        files: [TYPESCRIPT_SCRIPTS_SCOPE],
    },
]);

Если в проекте есть файлы typescript, которые не добавлены в tsconfig.json, или исключены из него принудительно, то eslint выдаст ошибку <filename> was not found by the project service. Consider either including it in the tsconfig.json or including it in allowDefaultProject. Есть несколько способов решения этой проблемы:

• (Рекомендуется) Добавить нужные файлы через опцию allowDefaultProject:

import { defineConfig, eslintConfig, TYPESCRIPT_SCRIPTS_SCOPE } from 'arui-presets-lint/eslint';

export default defineConfig(eslintConfig, [
    {
        languageOptions: {
            parserOptions: {
                projectService: {
                    // Это позволит eslint линтить файлы, даже если они не указаны в tsconfig.json
                    // Обратите внимание, что включить '**' тут нельзя, влияет на производительность!
                    // https://typescript-eslint.io/packages/parser/#allowdefaultproject
                    // Конкретно тут - разрешаем линтить все файлы с расширениями .ts, .mts и .cts в корневой директории проекта
                    allowDefaultProject: ['*.ts', '*.mts', '*.cts'],
                },
            },
        },
        files: [TYPESCRIPT_SCRIPTS_SCOPE],
    },
]);

• (НЕ рекомендуется) Добавить файлы в globalIgnores. В этом случае eslint не будет его проверять:

import { defineConfig, globalIgnores, eslintConfig } from 'arui-presets-lint/eslint';

export default defineConfig(eslintConfig, [
    {
        globalIgnores(['eslint.config.mts', 'arui-scripts.config.ts', 'playwright.config.ts']),
    },
]);

Конфигурация скриптов для запуска в package.json:

{
    "scripts": {
        "lint:styles": "arui-presets-lint styles",
        "lint:scripts": "arui-presets-lint scripts",
        "format": "arui-presets-lint format",
        "format:check": "arui-presets-lint format:check",
        "lint": "yarn lint:styles && yarn lint:scripts && yarn format:check",
        "lint:fix": "yarn lint:styles --fix && yarn lint:scripts --fix && yarn format"
    }
}

Чтобы eslint / stylelint / prettier не проверял конкретные файлы и папки, можно исключить их с помощью файлов .stylelintignore / .prettierignore / .eslintignore Прописывать там файлы, которые уже есть в .gitignore не требуется!

Вместо файла .eslintignore рекомендуется использовать globalIgnores в конфиге eslint (подробнее). Импортируем функцию globalIgnores из arui-presets-lint вот так:

import { defineConfig, globalIgnores } from 'arui-presets-lint/eslint';
...

Для запуска eslint/stylelint рекомендуется использовать флаг --max-warnings, который позволяет ограничить количество возникающих предупреждений.

Пример такой конфигурации:

{
    "scripts": {
        "lint:styles": "arui-presets-lint styles --max-warnings=0",
        "lint:scripts": "arui-presets-lint scripts --max-warnings=0",
        ...
    }
}

Настройка lefthook

Создайте в корне проекта файл lefthook.yml, он должен содержать следующее:

extends:
    - ./node_modules/arui-presets-lint/lefthook/index.yml

Затем подключите хуки к репозиторию: npx --no-install lefthook install

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

extends:
    - ./node_modules/arui-presets-lint/lefthook/index.yml

pre-commit:
    commands:
        # Добавить сборку typescript на pre-commit:
        check-ts:
            run: npx --no-install tsc --noEmit

        # Запустить тесты, относящиеся к измененному файлу:
        run-tests:
            glob: '*.{js,ts,jsx,tsx,mts,mjs,cjs,cts}'
            run: npx --no-install jest --findRelatedTests --passWithNoTests {staged_files}

pre-push:
    commands:
        # Запустить команду 'lint' на pre-push:
        run-lint:
            run: yarn lint

Гибкая конфигурация

Так как yarn run в yarn 2+ не поддерживает возможность запускать бинарные файлы, которые не установлены как прямые зависимости, а yarn dlx не умеет запускать бинарники без скачивания его из npm, существует возможность это сделать через вызов npx --no-install ...:

# Применить конфигурацию lefthook:
npx --no-install lefthook install

# Вызов prettier, для того чтобы отформатировать только js и jsx файлы:
npx --no-install prettier --write "./**/*.{js,jsx}" --no-error-on-unmatched-pattern --cache

# Вызов eslint, для того чтобы проверить только js и jsx файлы:
npx --no-install eslint "**/*.{js,jsx}"

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

Дебаг

Если нужно увидеть в консоли чему именно соответствует алиас в cli-утилите, нужно запустить arui-presets-lint с флагом --echo, например:

yarn arui-presets-lint --echo format
# >> prettier --write "./**/*.{ts,tsx,js,jsx,mjs,mts,cjs,cts,css,json}" --no-error-on-unmatched-pattern --cache

Если нужно посмотреть, какой именно конфиг применяется в текущем проекте:

# eslint:
npx --no-install eslint --print-config file.tsx > eslintconfig.json

# eslint в удобном ui-инспекторе:
npx @eslint/config-inspector@latest

# stylelint:
npx --no-install stylelint --print-config file.css > stylelintconfig.json

# commitlint:
npx --no-install commitlint --print-config > commitlintconfig.txt

Настройка IDE:

1. Включить ESLint
   • Расширение для VS Code
   • Инструкция для Webstorm
2. Включить Stylelint
   • Расширение для VS Code
   • Инструкция для Webstorm
3. Включить Prettier
   • Расширение для VS Code
   • Инструкция для Webstorm