Mika Quest

Семейная платформа квестов для детей. Основан на React-шаблоне отдела (React + TypeScript + Vite). Включает линтеры, форматтеры, проверку архитектуры FSD, тесты и пре-коммит хуки.

Документация

Документ	Назначение
docs/README.md	Индекс документации
plan.md	Исполняемый план для агентов
docs/planning/development-plan.md	Roadmap и DoD
docs/planning/bmad-brainstorm.md	BMAD: vision, архитектура
docs/planning/forgejo-backlog.md	Issues и порядок MVP
docs/ops/homelab.md	Деплой в homelab

Зависимости

Основные (production)

Пакет	Назначение
react, react-dom	React 19
react-router-dom	Маршрутизация SPA
tailwindcss	Стили, утилитарный CSS
@tailwindcss/vite	Интеграция Tailwind v4 с Vite

Разработка (devDependencies)

Сборка и запуск:

• vite — сборщик (через rolldown-vite): в проекте Vite подменён на rolldown-vite через overrides в package.json, поэтому сборка выполняется движком Rolldown
• @vitejs/plugin-react-swc — React + SWC
• typescript — TypeScript
• tsx — запуск TypeScript-скриптов без сборки

Линтинг и форматирование:

• eslint — линтер JS/TS (flat config)
• typescript-eslint — правила TypeScript
• eslint-plugin-react-hooks, eslint-plugin-react-refresh — React
• oxfmt — форматирование JS/TS/JSON/Markdown
• eslint-plugin-sonarjs — доп. правила качества кода
• eslint-plugin-jsx-a11y — правила доступности (a11y) для JSX
• stylelint — линтер CSS (стандарт + порядок свойств, БЭМ-паттерн для классов)

Архитектура и качество:

• steiger — проверка FSD (Feature-Sliced Design)
• knip — неиспользуемые зависимости, экспорты, файлы
• jscpd — поиск дубликатов кода

Тестирование:

• vitest — тестовый раннер для unit-тестов (совместим с Vite)
• @playwright/test — e2e-тесты в браузере

Прочее:

• husky — Git-хуки (pre-commit)
• @inquirer/prompts — интерактивное меню скриптов
• Типы: @types/node, @types/react, @types/react-dom
• vite-plugin-checker — проверка TypeScript, ESLint и Stylelint в dev-режиме

Что настроено

Vite (vite.config.ts)

• Плагины: React (SWC), Tailwind, checker (TS + ESLint + Stylelint в фоне).
• Алиас @ → src.
• base: './' для корректных путей при раздаче из подпапки.
• Vitest: unit-тесты из src (папка tests/e2e исключена из запуска Vitest).
• Checker линтит и src, и tests/e2e (ESLint).

TypeScript

• tsconfig.json — база, paths @/* → src/*, проектные ссылки на app, node и e2e.
• tsconfig.app.json — приложение: ES2022, strict, JSX, noUnusedLocals/noUnusedParameters, пути @/*, только src и types (сборка не включает тесты).
• tsconfig.node.json — конфиги и скрипты (Vite, scripts/).
• tsconfig.e2e.json — e2e-тесты в tests/e2e: типы Node и Playwright, пути @/* → src/* для возможных импортов из приложения.

ESLint (eslint.config.js)

• Рекомендованные наборы: JS, TypeScript, React Hooks, React Refresh, Prettier.
• Плагины: Prettier (как правило), SonarJS (часть правил отключена).
• Игнор: dist, node_modules, public, report.

Oxfmt (.oxfmtrc.json)

• Табы, ширина 80, одинарные кавычки, trailingComma: "es5", arrowParens: "avoid".

Stylelint (.stylelintrc)

• stylelint-config-standard, stylelint-config-clean-order.
• Паттерн классов в стиле БЭМ (block, block__element, block_modifier и т.п.).

Tailwind

• Версия 4, подключение через @tailwindcss/vite.
• В src/shared/base.css: @import 'tailwindcss'.
• tailwind.config.ts — content по ./src/**/*.{html,js,jsx,ts,tsx}.

FSD (Steiger) (steiger.config.ts)

• Рекомендованные правила Feature-Sliced Design.
• Отключены: insignificant-slice, excessive-slicing, shared-lib-grouping.
• Проверка каталога ./src/**.

Knip (knip.json)

• Точка входа: src/app/index.tsx.
• Включён экспорт из entry.
• Игнор: *.config.ts, unit- и e2e-тесты (__test__, tests/e2e), часть каталогов.

JSCPD (.jscpdrc.json)

• Поиск дубликатов: порог 50%, минимум 5 строк и 50 токенов.
• Форматы: TypeScript, TSX, JavaScript, JSX.
• Репорты: консоль и HTML.
• Учитывается .gitignore. Игнор: unit-тесты (__test__), e2e (__e2e__, tests/e2e).

Git (Husky)

• В .husky используется хук pre-commit, который запускает npm run check:pre-commit. При коммите выполняются: проверка FSD (steiger), Knip, Stylelint, ESLint, tsc -b --noEmit и тесты. Хуки настраиваются при установке зависимостей через npm run prepare (husky).

Формат коммитов (Conventional Commits): сообщения коммитов проверяются хуком commit-msg с помощью commitlint. Формат: тип: краткое описание (например, feat: добавлена страница входа, fix: исправлена ошибка в форме). Допускаются типы: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert. При несоответствии формата коммит не создаётся, в консоли выводится подсказка от commitlint.

Скрипты и меню

• npm run menu — интерактивное меню (scripts/run.ts + scripts/menu.config.ts): запуск dev, линтеры (format, lint, fsd, дубликаты, knip, oxfmt, фиксы), тесты (run, ui, coverage, watch), сборка и preview.
• Остальные команды — как в package.json (dev, build, lint, format, test и т.д.).

Структура приложения

• Точка входа: index.html → src/app/index.tsx.
• Рендер в #root, подключение App и глобальных стилей @/shared/base.css.
• Приложение обёрнуто в HashRouter (react-router-dom); маршруты объявлены в App.tsx через Routes и Route.
• Слои FSD: app (точка входа, роуты), pages (страницы), widgets (составные блоки, например Error Boundary), shared (общие стили, утилиты, модели). По мере роста приложения можно добавлять слои entities, features — правила и приоритеты слоёв описаны в .cursor/rules/rules-fsd.mdc.

Глобальная обработка ошибок

• В корне приложения используется Error Boundary (src/widgets/error-boundary): перехватывает ошибки рендеринга в дереве компонентов, чтобы падение одного компонента не роняло всё приложение.
• При ошибке показывается fallback («Что-то пошло не так» и кнопка «Перезагрузить»), ошибка логируется в консоль.

Роутинг

• Используется HashRouter: адреса вида ...#/ и ...#/путь (например, index.html#/ — главная).
• Маршруты: / — главная страница (Home), * — страница «Не найдена» (404).
• Как добавить страницу: создать срез в src/pages/<имя> (например, компонент страницы в ui/, экспорт в public/index.ts), затем в App.tsx добавить <Route path="..." element={<НоваяСтраница />} />.

Запуск

npm install
npm run dev      # режим разработки
npm run build    # сборка
npm run preview  # просмотр сборки
npm run menu     # меню скриптов

Линтинг и форматирование: npm run format, npm run lint, npm run lint:fix, npm run stylelint:fix, npm run oxfmt:write. Проверка FSD: npm run fsd. Unit-тесты: npm run test, npm run test:ui, npm run test:coverage. E2E: npm run test:e2e, npm run test:e2e:ui.

E2E-тесты

E2E-тесты выполняются с помощью Playwright и проверяют ключевые сценарии в браузере. Размещаются в корневой папке проекта tests/e2e (на одном уровне с src), группировка по фичам, например: tests/e2e/error-boundary/ErrorBoundary.spec.tsx. Конфиг Playwright: testDir: 'tests/e2e', маска **/*.spec.{ts,tsx}. Файлы в tests/e2e линтируются ESLint (vite-plugin-checker и общий scope ESLint), типизируются через tsconfig.e2e.json, не входят в сборку приложения и не запускаются Vitest.

Запуск локально:

1. При первом запуске установите браузеры: npx playwright install
2. Поднимите приложение в отдельном терминале: npm run preview (по умолчанию порт 4173)
3. Запустите E2E: npm run test:e2e

Для интерактивного режима с UI: npm run test:e2e:ui (приложение должно быть запущено).

Что проверяет пример: открытие страницы с ошибкой (/#/error-boundary-demo), отображение fallback Error Boundary и кнопки «Перезагрузить», перезагрузка страницы при клике. Пример — в tests/e2e/error-boundary/.

Переменные окружения

Локальные переменные окружения задаются в файле .env в корне проекта. Репозиторий содержит только шаблон — .env.example (без секретов).

Как настроить:

1. Скопировать .env.example в .env:
2. Заполнить в .env нужные значения. Файл .env не попадает в Git (см. .gitignore).

Ожидаемые переменные:

Переменная	Назначение
VITE_API_BASE_URL	Базовый URL API (например, бэкенда)

В коде переменные доступны через import.meta.env.VITE_* (типы заданы в src/vite-env.d.ts).

Favicon

Иконка сайта берётся из public/favicon.ico (в index.html указано href="/favicon.ico"). Чтобы заменить иконку, положите свой файл favicon.ico в каталог public/ или замените существующий.

Использование как шаблон

1. Клонировать репозиторий.
2. Заменить поле name в package.json на имя нового проекта.
3. При необходимости удалить или заменить демо-код (например, store в src/shared/models, использование в App.tsx).