Практическое руководство по настройке ESLint v9+ (Flat Config) для стека React + TypeScript, по методологии Feature-Sliced Design (FSD)

Вот готовое практическое руководство по настройке ESLint v9+ (Flat Config) для стека React + TypeScript и созданию структуры папок по методологии Feature-Sliced Design (FSD).

Современный ESLint (начиная с версии 9) использует новый формат конфигурации eslint.config.js (Flat Config).

Выполните команду в терминале проекта:

npm install -D eslint @eslint/js typescript-eslint eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-react-refresh

Создайте этот файл в корневом каталоге проекта:

import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import reactPlugin from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';
import reactRefresh from 'eslint-plugin-react-refresh';

export default tseslint.config(
  // Игнорируемые папки (замена старого .eslintignore)
  { ignores: ['dist', 'node_modules', 'build'] },
  
  // Базовые настройки для JavaScript и TypeScript
  js.configs.recommended,
  ...tseslint.configs.recommended,
  
  // Настройки для React-компонентов
  {
    files: ['**/*.{ts,tsx}'],
    plugins: {
      'react': reactPlugin,
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh,
    },
    languageOptions: {
      parserOptions: {
        ecmaFeatures: { jsx: true },
      },
    },
    settings: {
      react: { version: 'detect' }, // Автоопределение версии React
    },
    rules: {
      // Правила React Hooks
      ...reactHooks.configs.recommended.rules,
      
      // Специфичные правила для React
      'react/react-in-jsx-scope': 'off', // Отключено для React 17+
      'react/jsx-no-target-blank': 'warn',
      
      // Правила для React Fast Refresh (полезно для Vite)
      'react-refresh/only-export-components': [
        'warn',
        { allowConstantExport: true },
      ],
      
      // Кастомные правила TypeScript
      '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
      '@typescript-eslint/no-explicit-any': 'warn',
    },
  }
);

Методология FSD делит проект на слои (Layers), внутри которых находятся слайсы (Slices), разбитые на сегменты (Segments). Главное правило: верхние слои могут импортировать код только из нижних, но не наоборот.

Вот как выглядит правильная структура каталога src для типичного React-приложения:

src/
├── 1_app/                  # Слои (Layers) пишутся строчными буквами, цифры — для визуального порядка
│   ├── providers/          # Провайдеры (Redux Store, RouterProvider, ThemeProvider)
│   ├── styles/             # Глобальные стили (index.css, variables.scss)
│   └── App.tsx             # Инициализация приложения
│
├── 2_pages/                # Страницы приложения
│   ├── home/               # Слайс страницы (Slice)
│   │   ├── ui/             # Сегменты (Segments): UI-компоненты страницы
│   │   └── index.ts        # Публичное API (только отсюда можно делать импорт наружу!)
│   └── profile/
│       ├── ui/
│       └── index.ts
│
├── 3_widgets/              # Крупные самостоятельные блоки (из фич и сущностей)
│   ├── header/
│   │   ├── ui/             # Header.tsx
│   │   └── index.ts
│   └── sidebar/
│
├── 4_features/             # Действия пользователя, несущие бизнес-ценность
│   ├── auth-by-username/   # Авторизация
│   │   ├── model/          # Стейт, экшены, селекторы (Redux/Zustand)
│   │   ├── ui/             # Форма логина, кнопка
│   │   └── index.ts
│   └── add-to-cart/        # Добавление в корзину
│
├── 5_entities/             # Бизнес-сущности (без привязки к конкретным действиям)
│   ├── user/
│   │   ├── model/          # Типы пользователя, стейт авторизации
│   │   └── index.ts
│   └── product/
│       ├── ui/             # Карточка продукта (ProductCard)
│       └── index.ts
│
└── 6_shared/               # Переиспользуемый код (инфраструктура, утилиты)
    ├── api/                # Базовые запросы (axios, fetch)
    ├── assets/             # Иконки, картинки, шрифты
    ├── lib/                # Хелперы, кастомные хуки (useDebounce и др.)
    └── ui/                 # Атомарные UI-компоненты (Button, Input, Modal)
        ├── button/
        │   ├── Button.tsx
        │   └── index.ts
        └── input/

1. Индексные файлы (index.ts) — это «ворота» слайса. Извне разрешено импортировать код только через них (например: import { Button } from '@/shared/ui/button'). Импорты вида .../button/Button.tsx строго запрещены.
2. Иерархия импортов — widgets может импортировать из features, entities и shared. Но shared не может импортировать ничего из слоев выше.