refactor(repo): переход на pnpm monorepo с shadcn/ui и Fastify+Drizzle
Frontend:
- apps/web (Vite+TS, TanStack Router/Query, shadcn/ui @cfdm/ui base-nova)
- 10 страниц в routes/_auth/, Recharts через shadcn Chart, lucide-react
- формы на RHF + Zod (FormSheet/FormField)
- удалены Tabler, Chart.js, react-router-dom
Backend (параллельный трек):
- apps/api (Fastify 5 + Drizzle + better-sqlite3)
- packages/db: Drizzle-схема и repositories по сущностям
- packages/shared: Zod-контракты
- роуты с валидацией и единым форматом ошибок { error: { code, message } }
- sync/backup — заглушки 501 (billmanager-адаптеры переносятся отдельно)
- legacy Express оставлен как runtime по умолчанию (RUNTIME=express)
Infra:
- Dockerfile multi-stage под pnpm workspaces
- .dockerignore и docker-compose обновлены под monorepo
Rules:
- удалены нерелевантные правила (rust, cloudflare, server/frontend-conventions)
- project-structure.mdc и AGENTS.md переписаны под monorepo
- frontend-shadcn.mdc, shadcn-ui-production.mdc, sqlite.mdc обновлены
Co-authored-by: Cursor <[email protected]>
This commit is contained in:
Denozordec
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"codegraph": {
|
||||
"type": "stdio",
|
||||
"command": "codegraph",
|
||||
"args": [
|
||||
"serve",
|
||||
"--mcp",
|
||||
"--path",
|
||||
"C:\\Users\\shats\\Dev\\cloudflare-domain-manager"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
description: Concise AI assistant — clean code, token efficiency, codebase alignment
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# AI Coding Assistant
|
||||
|
||||
You work inside a real codebase. Be precise, concise, and aligned with existing patterns.
|
||||
|
||||
## Clean Code
|
||||
|
||||
- Minimal, readable, maintainable code; simple over clever
|
||||
- Meaningful names; DRY; small single-responsibility functions
|
||||
- Follow existing project style and patterns
|
||||
|
||||
## Token Efficiency
|
||||
|
||||
- Do not explain obvious things
|
||||
- No step-by-step reasoning unless explicitly asked
|
||||
- Output only what is necessary: code, brief comments when needed
|
||||
- No long prose, summaries, or repetition
|
||||
- If unsure — ask a short clarifying question instead of guessing
|
||||
|
||||
## Work With Existing Codebase
|
||||
|
||||
- Analyze surrounding code before generating new code
|
||||
- Reuse existing utilities, helpers, and patterns
|
||||
- Do not reinvent functionality already in the project
|
||||
- Respect project architecture
|
||||
|
||||
## Documentation Awareness
|
||||
|
||||
- Check project docs, README, comments, and types before implementing
|
||||
- If behavior is unclear: infer from types/tests/examples, or ask
|
||||
- Prefer documented approaches over assumptions
|
||||
|
||||
## Output Format
|
||||
|
||||
- Default: only code
|
||||
- If explanation is required — keep it under 3–5 lines
|
||||
- Highlight only important decisions
|
||||
|
||||
## Refactoring
|
||||
|
||||
- Preserve behavior unless told otherwise
|
||||
- Improve readability and structure; reduce complexity and duplication
|
||||
|
||||
## Debugging
|
||||
|
||||
- Identify root cause, not symptoms
|
||||
- Suggest minimal fix; avoid rewriting large parts unless necessary
|
||||
|
||||
## Missing Context
|
||||
|
||||
- Ask concise, targeted questions
|
||||
- Do not hallucinate APIs or project structure
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
description: Backend API — при изменениях, затрагивающих UI, строго следовать shadcn Components/Blocks
|
||||
globs: apps/api/**/*,packages/shared/**/*
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Backend API + shadcn/ui
|
||||
|
||||
Fastify backend: `apps/api/`. Контракты — `@cfdm/shared` (Zod). Frontend — TanStack Query.
|
||||
|
||||
## Обязательный порядок
|
||||
|
||||
1. **Backend** — route, service, Vitest (`app.inject()`)
|
||||
2. **Схемы** — `@cfdm/shared` (не дублировать в `apps/web/src/lib/schemas.ts`)
|
||||
3. **UI** — shadcn MCP ([`shadcn-mcp.mdc`](shadcn-mcp.mdc))
|
||||
|
||||
## Запрещено на frontend при доработке API
|
||||
|
||||
- Новые raw `<table>` / `<select>` / кастомные badge-цвета
|
||||
- Дублирование Zod schemas в `apps/web` — только re-export из `@cfdm/shared`
|
||||
- Самописные формы без `Field` + RHF + Zod
|
||||
|
||||
## shadcn-паттерны
|
||||
|
||||
| API-данные | UI |
|
||||
|------------|-----|
|
||||
| Список | `Table` / `DataTableCard` |
|
||||
| Создание | `Card` + `FieldGroup` + RHF |
|
||||
| Статус | `Badge` variants |
|
||||
| Ошибка | `sonner` `toast.error` |
|
||||
|
||||
## Согласованность
|
||||
|
||||
- JSON поля — snake_case как в существующем API
|
||||
- Новый endpoint → `queryOptions` в `apps/web/src/queries/`
|
||||
|
||||
MCP backend: [`backend-mcp.mdc`](backend-mcp.mdc) · Fastify: [`backend-fastify.mdc`](backend-fastify.mdc)
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
description: Drizzle ORM + SQLite — schema, migrations, queries
|
||||
globs: packages/db/**/*,apps/api/src/services/**/*
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Backend Drizzle
|
||||
|
||||
MCP Context7 (`drizzle-orm`, `drizzle-kit`) — [`backend-mcp.mdc`](backend-mcp.mdc).
|
||||
|
||||
## Schema
|
||||
|
||||
- `packages/db/src/schema/` — source of truth
|
||||
- Migrations: `drizzle-kit generate` / `migrate`
|
||||
- WAL + `foreign_keys` при открытии SQLite
|
||||
- Индекс `idx_dns_records_domain_cf_id` на `(domain_id, cf_record_id)`
|
||||
|
||||
## Queries
|
||||
|
||||
- Batch queries (`inArray`, JOINs) — не N+1 loops
|
||||
- UNIQUE violations → `CONFLICT` (409)
|
||||
- Multi-step → `db.transaction()`
|
||||
|
||||
## SQLite
|
||||
|
||||
См. [`sqlite.mdc`](sqlite.mdc).
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
description: Fastify API — слои, плагины, контракт ошибок
|
||||
globs: apps/api/**/*
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Backend Fastify
|
||||
|
||||
Стек: **Node.js 22**, **Fastify 5**, `@fastify/*` plugins, `@cfdm/shared`, `@cfdm/db`.
|
||||
|
||||
MCP — [`backend-mcp.mdc`](backend-mcp.mdc).
|
||||
|
||||
## Слои
|
||||
|
||||
```
|
||||
routes/ → services/ → @cfdm/db (repositories)
|
||||
↘ lib/cf-client.ts
|
||||
```
|
||||
|
||||
- Routes — тонкие Fastify plugins (`fastify-plugin`)
|
||||
- **Запрещено:** SQL в routes, `fetch` к CF вне `cf-client`
|
||||
|
||||
## Плагины (официальные)
|
||||
|
||||
`@fastify/jwt`, `@fastify/cors`, `@fastify/sensible`, `@fastify/static`, `@fastify/helmet`, `@fastify/rate-limit`, `@fastify/type-provider-zod`, `fastify-plugin`
|
||||
|
||||
## Ошибки
|
||||
|
||||
Формат: `{ error: { code, message } }`
|
||||
|
||||
Коды: `NOT_FOUND`, `VALIDATION_ERROR`, `UNAUTHORIZED`, `FORBIDDEN`, `CONFLICT`, `CLOUDFLARE_ERROR`, `INTERNAL_ERROR`
|
||||
|
||||
## Правила
|
||||
|
||||
- Zod schemas только из `@cfdm/shared`
|
||||
- `db.transaction()` для multi-step writes
|
||||
- Операции >2s → async job (`sync_jobs` + `p-queue`)
|
||||
- Env через Zod в `config.ts`; prod fail-fast на dev `JWT_SECRET`
|
||||
- TypeScript strict; `function` для handlers/services
|
||||
|
||||
## API + UI
|
||||
|
||||
[`backend-api-ui.mdc`](backend-api-ui.mdc)
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
description: Обязательный порядок MCP перед backend-кодом (Fastify, Drizzle, Cloudflare API)
|
||||
globs: apps/api/**/*,packages/db/**/*,packages/shared/**/*
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Backend MCP — обязательно
|
||||
|
||||
Перед **любой** задачей в `apps/api`, `packages/db`, `packages/shared` — сначала MCP, не training data.
|
||||
|
||||
## Порядок
|
||||
|
||||
| Задача | MCP |
|
||||
|--------|-----|
|
||||
| Fastify plugins, routes, hooks | **Context7** `resolve-library-id` → `query-docs` (`fastify`, `@fastify/jwt`, `@fastify/type-provider-zod`) |
|
||||
| Drizzle schema, queries, migrations | **Context7** (`drizzle-orm`, `drizzle-kit`, `better-sqlite3`) |
|
||||
| Cloudflare DNS/Zones API | **`plugin-cloudflare-cloudflare-docs`** `search_cloudflare_documentation` |
|
||||
| API + UI | `packages/shared` → **shadcn MCP** ([`shadcn-mcp.mdc`](shadcn-mcp.mdc)) |
|
||||
| E2E / cutover | **cursor-ide-browser** |
|
||||
| Неизвестный инструмент | **user-mcp-on-demand** `search_tools` |
|
||||
|
||||
## Запрещено
|
||||
|
||||
- Угадывать API Fastify/Drizzle/CF из памяти
|
||||
- Самописные аналоги `@fastify/*` (CORS, static, JWT, rate-limit)
|
||||
- Дублировать Zod schemas вне `@cfdm/shared`
|
||||
|
||||
Связанные: [`backend-fastify.mdc`](backend-fastify.mdc), [`backend-drizzle.mdc`](backend-drizzle.mdc), [`backend-testing.mdc`](backend-testing.mdc).
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
description: Backend Vitest + Fastify inject
|
||||
globs: apps/api/**/*,packages/db/**/*,packages/shared/**/*
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Backend Testing
|
||||
|
||||
Vitest + `app.inject()` (встроено в Fastify).
|
||||
|
||||
## Требования
|
||||
|
||||
- Каждый route plugin → минимум 1 integration test
|
||||
- Sync/DNS → parity fixtures
|
||||
- `:memory:` SQLite для unit; file DB для integration
|
||||
- `beforeEach` — fresh schema migrate
|
||||
|
||||
## Паттерн
|
||||
|
||||
```ts
|
||||
const app = await buildApp({ db: testDb })
|
||||
const res = await app.inject({ method: 'GET', url: '/health' })
|
||||
expect(res.statusCode).toBe(200)
|
||||
```
|
||||
|
||||
См. [`vitest-best-practices.mdc`](vitest-best-practices.mdc).
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
description: Conventional commits на русском языке
|
||||
globs: "**/*"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Commit messages (русский)
|
||||
|
||||
Формат: `<type>[optional scope]: <описание>`
|
||||
|
||||
## Типы
|
||||
|
||||
- `feat` — только новая UX-фича для пользователя
|
||||
- `fix` — исправление бага
|
||||
- `chore` — конфиг, зависимости, правила, CI
|
||||
- `refactor` — рефакторинг без изменения поведения
|
||||
- `docs` — документация
|
||||
- `test` — тесты
|
||||
- `perf` — производительность
|
||||
|
||||
## Правила
|
||||
|
||||
- Subject в **императиве**, без точки в конце
|
||||
- Subject и body — **на русском**
|
||||
- Body (опционально) — что и зачем, не как
|
||||
- Scope в скобках при необходимости: `feat(domains): добавить фильтр по статусу`
|
||||
|
||||
## Примеры
|
||||
|
||||
```
|
||||
fix(frontend): заменить raw table на shadcn Table на странице доменов
|
||||
|
||||
feat(certificates): добавить предупреждение об истечении срока
|
||||
|
||||
chore(rules): консолидировать правила shadcn/ui для Cursor
|
||||
```
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
description: Паттерны для React, api, utils
|
||||
globs: src/**/*.{js,jsx}
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Frontend conventions
|
||||
|
||||
## React
|
||||
|
||||
- Функциональные компоненты
|
||||
- Страницы в `pages/`, общие компоненты в `components/`
|
||||
- Данные загружаются в App.jsx через `loadDataSet()`, передаются в страницы как `db` и `actions`
|
||||
|
||||
## API
|
||||
|
||||
- `src/lib/api.js` — fetchApi, loadDataSet, createRecord, updateRecord, deleteRecord
|
||||
- Коллекции: vps, providers, providerAccounts, payments, balanceLedger, settings
|
||||
- Дополнительно: syncAccount, fetchAccountBalance, testApiConnection
|
||||
|
||||
## Utils
|
||||
|
||||
- `src/lib/utils.js` — форматирование (formatCurrency), конвертация валют, лейблы (paymentTypeLabel), CSV
|
||||
@@ -0,0 +1,103 @@
|
||||
---
|
||||
description: shadcn/ui Monorepo — структура apps/web + packages/ui, CLI workflow, импорты @cfdm/ui
|
||||
globs: apps/web/**/*,packages/ui/**/*
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Frontend Monorepo (shadcn/ui)
|
||||
|
||||
**Обязательный стандарт структуры** — [Monorepo docs](https://ui.shadcn.com/docs/monorepo).
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
apps/web/ # Vite SPA (routes, queries, domain components)
|
||||
apps/api/ # Fastify API + static SPA in prod
|
||||
packages/ui/ # @cfdm/ui — shadcn primitives
|
||||
packages/shared/ # @cfdm/shared — Zod schemas, parse-fqdn
|
||||
packages/db/ # @cfdm/db — Drizzle schema, repositories
|
||||
```
|
||||
|
||||
## Два components.json
|
||||
|
||||
| Файл | Назначение |
|
||||
|------|------------|
|
||||
| [`apps/web/components.json`](apps/web/components.json) | App aliases; `ui` → `@cfdm/ui/components` |
|
||||
| [`packages/ui/components.json`](packages/ui/components.json) | UI package aliases |
|
||||
|
||||
**Синхронизировать:** `style`, `iconLibrary`, `baseColor` в обоих файлах.
|
||||
|
||||
## CLI — только из apps/web
|
||||
|
||||
```bash
|
||||
cd apps/web
|
||||
pnpm dlx shadcn@latest docs button
|
||||
pnpm dlx shadcn@latest add button
|
||||
pnpm dlx shadcn@latest add sidebar-07
|
||||
pnpm dlx shadcn@latest add login-03
|
||||
pnpm dlx shadcn@latest apply b2fA --only theme -y
|
||||
```
|
||||
|
||||
Перед обновлением существующих компонентов:
|
||||
|
||||
```bash
|
||||
pnpm dlx shadcn@latest add button --dry-run
|
||||
pnpm dlx shadcn@latest add button --diff
|
||||
pnpm dlx shadcn@latest info --json
|
||||
```
|
||||
|
||||
## Куда CLI кладёт файлы
|
||||
|
||||
| Команда | Куда |
|
||||
|---------|------|
|
||||
| `add button` | `packages/ui/src/components/button.tsx` |
|
||||
| `add login-03` | примитивы → `packages/ui`, block → `apps/web/src/components/` |
|
||||
|
||||
## Импорты
|
||||
|
||||
```tsx
|
||||
import { Button } from '@cfdm/ui/components/button'
|
||||
import { cn } from '@cfdm/ui/lib/utils'
|
||||
import { useIsMobile } from '@cfdm/ui/hooks/use-mobile'
|
||||
import '@cfdm/ui/globals.css' // только в main.tsx
|
||||
```
|
||||
|
||||
| Запрещено | Разрешено |
|
||||
|-----------|-----------|
|
||||
| `@/components/ui/*` | `@cfdm/ui/components/*` |
|
||||
| `apps/web/src/components/ui/` | `packages/ui/src/components/` |
|
||||
| Ручное редактирование `globals.css` | `pnpm dlx shadcn@latest apply b2fA --only theme` |
|
||||
|
||||
Community registry: переписывать импорты на `@cfdm/ui/...`.
|
||||
|
||||
## Разделение ответственности
|
||||
|
||||
- **`packages/ui`** — только output `shadcn add` (примитивы, registry hooks, `cn`)
|
||||
- **`apps/web/src/components`** — blocks, layout, domain (`login-form`, `app-shell`, `PageHeader`)
|
||||
|
||||
## Стили (Tailwind v4 monorepo)
|
||||
|
||||
`packages/ui/src/styles/globals.css` — единственный CSS-файл. **Обязательно** `@source` для обоих workspace:
|
||||
|
||||
```css
|
||||
@source "../"; /* packages/ui/src */
|
||||
@source "../../../apps/web/src"; /* apps/web/src */
|
||||
```
|
||||
|
||||
Без `@source` Tailwind не видит классы из `packages/ui` и `apps/web` — UI ломается (нет sidebar, card, и т.д.).
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm --filter web dev
|
||||
pnpm --filter web build
|
||||
```
|
||||
|
||||
## Чеклист
|
||||
|
||||
- [ ] Два `components.json` согласованы
|
||||
- [ ] `shadcn add` из `apps/web`
|
||||
- [ ] UI-импорты через `@cfdm/ui/components/*`
|
||||
- [ ] Нет `apps/web/src/components/ui/`
|
||||
- [ ] `pnpm --filter web build` без ошибок
|
||||
|
||||
См. также: [`frontend-shadcn.mdc`](frontend-shadcn.mdc), [`vite-tanstack-frontend.mdc`](vite-tanstack-frontend.mdc).
|
||||
@@ -0,0 +1,197 @@
|
||||
---
|
||||
description: Frontend — ТОЛЬКО shadcn/ui docs (Components, Blocks, Installation); best practices, CLI-first
|
||||
globs: apps/web/**/*,packages/ui/**/*
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Frontend — shadcn/ui (обязательно)
|
||||
|
||||
**Источник истины — MCP shadcn + официальная документация.** Не выдумывать UI, не писать кастомный CSS, не обходить MCP и CLI.
|
||||
|
||||
Monorepo layout — [`frontend-monorepo.mdc`](frontend-monorepo.mdc). MCP workflow — [`shadcn-mcp.mdc`](shadcn-mcp.mdc). UI patterns — [`frontend-ui-patterns.mdc`](frontend-ui-patterns.mdc).
|
||||
|
||||
| Документ | URL |
|
||||
|----------|-----|
|
||||
| **Components (primary catalog)** | https://ui.shadcn.com/docs/components |
|
||||
| **Blocks** | https://ui.shadcn.com/blocks |
|
||||
| **Installation** | https://ui.shadcn.com/docs/installation |
|
||||
| **Monorepo** | https://ui.shadcn.com/docs/monorepo |
|
||||
| **Theming** | https://ui.shadcn.com/docs/theming |
|
||||
| **Dark Mode** | https://ui.shadcn.com/docs/dark-mode |
|
||||
| **Forms (RHF)** | https://ui.shadcn.com/docs/forms/react-hook-form |
|
||||
|
||||
## Шаг 0 — перед любым UI-кодом
|
||||
|
||||
0. **Codegraph** `codegraph_explore` — найти существующие реализации
|
||||
1. **MCP `plugin-shadcn-shadcn`:** `search_items_in_registries` → `get_item_examples_from_registries` → `get_add_command_for_items` ([`shadcn-mcp.mdc`](shadcn-mcp.mdc))
|
||||
2. Открыть **Components** или **Blocks** — найти готовое решение
|
||||
3. `cd apps/web && pnpm dlx shadcn@latest docs <component>` — сверить API с [Components](https://ui.shadcn.com/docs/components)
|
||||
4. Сверить MCP examples ↔ docs API — только потом писать код
|
||||
5. `cd apps/web && pnpm dlx shadcn@latest search "@shadcn/<query>"` — если MCP не дал результат
|
||||
|
||||
**Новая страница** → сначала [Blocks](https://ui.shadcn.com/blocks), потом `pnpm dlx shadcn@latest add <block-id>`.
|
||||
|
||||
## Docs workflow
|
||||
|
||||
1. MCP `plugin-shadcn-shadcn` — search → examples → add command
|
||||
2. `pnpm dlx shadcn@latest docs <component>` — fetch URLs, сверить API
|
||||
3. Skill `.agents/skills/shadcn/SKILL.md` — critical rules
|
||||
4. Context7 — только TanStack / Recharts
|
||||
|
||||
## Shared components (обязательно)
|
||||
|
||||
| Component | Файл |
|
||||
|-----------|------|
|
||||
| `PageShell` | `page-shell.tsx` |
|
||||
| `PageHeader` | `page-header.tsx` |
|
||||
| `EmptyState` | `empty-state.tsx` |
|
||||
| `QueryState` | `query-state.tsx` |
|
||||
| `ConfirmDialog` | `confirm-dialog.tsx` |
|
||||
| `DataTableCard` | `data-table-card.tsx` |
|
||||
| `SectionCards` | `section-cards.tsx` |
|
||||
| `StatusBadge` | `status-badge.tsx` |
|
||||
| `FormSheet` | `form-sheet.tsx` |
|
||||
| `FormField` | `form-field.tsx` |
|
||||
| `TableCard` | `table-card.tsx` |
|
||||
| `LoadingButton` | `loading-button.tsx` |
|
||||
| `SectionCardsSkeleton` | `section-cards-skeleton.tsx` |
|
||||
| `TableSkeleton` | `table-skeleton.tsx` |
|
||||
|
||||
**Overlay:** Sheet — forms; AlertDialog — destructive confirm.
|
||||
|
||||
## Шаг 1 — CLI (обязательно)
|
||||
|
||||
```bash
|
||||
cd apps/web
|
||||
pnpm dlx shadcn@latest add table select badge card field input button ...
|
||||
pnpm dlx shadcn@latest add sidebar-07 # layout
|
||||
pnpm dlx shadcn@latest add dashboard-01 # dashboard
|
||||
pnpm dlx shadcn@latest add login-03 # auth
|
||||
pnpm dlx shadcn@latest apply b2fA --only theme -y # тема — ТОЛЬКО так
|
||||
```
|
||||
|
||||
- Копипаст с сайта **без** CLI — запрещено
|
||||
- `packages/ui/src/components/*` — только registry; domain-логика → `apps/web/src/components/<name>.tsx`
|
||||
|
||||
## Шаг 2 — композиция (best practices)
|
||||
|
||||
### Приоритет
|
||||
|
||||
1. Установленный `@cfdm/ui/components/*`
|
||||
2. Block из registry (адаптация под TanStack Router)
|
||||
3. Shared проекта: `PageShell`, `PageHeader`, `EmptyState`, `QueryState`, `ConfirmDialog`, `DataTableCard`, `SectionCards`, `StatusBadge`
|
||||
4. Domain-обёртка — последний уровень кастомизации
|
||||
|
||||
### Запрещено в apps/web
|
||||
|
||||
| ❌ | ✅ |
|
||||
|----|---|
|
||||
| `<table>`, `<select>`, `<hr>` | `Table`, `Select`, `Separator` из [Components](https://ui.shadcn.com/docs/components) |
|
||||
| `bg-emerald-*`, `text-blue-500`, hex в className | `bg-primary`, `text-muted-foreground`, `Badge variant` |
|
||||
| Ручной `globals.css`, `.css` модули | CLI `apply b2fA --only theme` |
|
||||
| `space-y-*` / `space-x-*` | `flex` + `gap-*` |
|
||||
| `w-10 h-10` | `size-10` |
|
||||
| `className` для цветов Button/Badge | `variant`, `size` |
|
||||
| `useState` для полей формы | `FieldGroup` + RHF + Zod |
|
||||
| Styled `<Link>` | `Button variant="link"` + `render={<Link />}` |
|
||||
| `inline style={{}}` в routes | layout Tailwind |
|
||||
| `animate-pulse` div | `Skeleton` |
|
||||
| кастомный toast | `sonner` → `toast()` |
|
||||
| `@/components/ui/*` | `@cfdm/ui/components/*` |
|
||||
|
||||
### Устаревшие библиотеки (миграция с Tabler)
|
||||
|
||||
| ❌ удалить | ✅ заменить на |
|
||||
|-----------|----------------|
|
||||
| `@tabler/core` (CSS-фреймворк) | Tailwind v4 + shadcn tokens |
|
||||
| `import '@tabler/core/dist/css/tabler.min.css'` в `main.tsx` | `import '@cfdm/ui/globals.css'` |
|
||||
| `@tabler/icons-react` (`Icon*`) | `lucide-react` (`<PlusIcon />` и т.п.) |
|
||||
| `chart.js` | `recharts` через shadcn `Chart`/`ChartContainer` |
|
||||
| `react-router-dom` (`<BrowserRouter>`, `<Routes>`, `useNavigate`) | TanStack Router (`createFileRoute`, `<Link>`, `useNavigate`) |
|
||||
| Bootstrap-классы Tabler (`page`, `navbar-vertical`, `nav-link`, `container-tight`, `spinner-border`, `d-lg-none`) | shadcn `AppShell` (sidebar-07), `Button`, `Skeleton` |
|
||||
| Prop-drilling `db` + `actions` из `App.jsx` | `useQuery`/`useMutation` + key factories в `queries/` |
|
||||
| `useState` + `loadDataSet()` в корне | `QueryClient` + route loaders (`ensureQueryData`) |
|
||||
|
||||
### Формы
|
||||
|
||||
По https://ui.shadcn.com/docs/forms/react-hook-form:
|
||||
|
||||
```tsx
|
||||
<FieldGroup>
|
||||
<Field data-invalid={!!errors.name}>
|
||||
<FieldLabel htmlFor="name">Имя</FieldLabel>
|
||||
<Input id="name" aria-invalid={!!errors.name} {...register('name')} />
|
||||
</Field>
|
||||
</FieldGroup>
|
||||
```
|
||||
|
||||
### Card
|
||||
|
||||
`CardHeader` / `CardTitle` / `CardDescription` / `CardContent` / `CardFooter` — полная композиция из docs.
|
||||
|
||||
### Таблицы
|
||||
|
||||
`Table`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell` — из docs.
|
||||
Сложная таблица → [Data Table](https://ui.shadcn.com/docs/components/data-table) + block `dashboard-01`.
|
||||
|
||||
### Графики
|
||||
|
||||
`Chart` + `ChartContainer` + `chartConfig` с `var(--chart-1)` — не raw recharts без обёртки.
|
||||
|
||||
### Иконки в Button
|
||||
|
||||
```tsx
|
||||
<Button>
|
||||
<PlusIcon data-icon="inline-start" />
|
||||
Создать
|
||||
</Button>
|
||||
```
|
||||
|
||||
Без `size-4` на иконке внутри shadcn-компонента.
|
||||
|
||||
## Стек (не shadcn, но обязателен)
|
||||
|
||||
TanStack Router + Query — [`vite-tanstack-frontend.mdc`](vite-tanstack-frontend.mdc).
|
||||
|
||||
- Preset: **base-nova** + **neutral** — [`apps/web/components.json`](apps/web/components.json), [`packages/ui/components.json`](packages/ui/components.json)
|
||||
- `@base-ui/react` → `render` prop (не Radix `asChild`)
|
||||
- **Не Next.js** — нет Server Components, `'use client'`
|
||||
|
||||
## Эталоны проекта
|
||||
|
||||
| Зона | Файл | Block |
|
||||
|------|------|-------|
|
||||
| Shell | `apps/web/src/components/layout/app-shell.tsx` | [sidebar-07](https://ui.shadcn.com/blocks) |
|
||||
| Login | `apps/web/src/routes/login.tsx` | [login-03](https://ui.shadcn.com/blocks) |
|
||||
| Dashboard | `apps/web/src/routes/_auth/index.tsx` | [dashboard-01](https://ui.shadcn.com/blocks) |
|
||||
| CRUD | `routes/_auth/services.tsx`, `domains/index.tsx` | Card + Field + Table |
|
||||
|
||||
## Структура файлов
|
||||
|
||||
```
|
||||
apps/web/src/
|
||||
components/ ← domain + layout + shared (blocks)
|
||||
routes/ ← страницы (композиция @cfdm/ui, без raw HTML)
|
||||
queries/ ← queryOptions (не inline в routes)
|
||||
lib/schemas.ts ← Zod для форм
|
||||
|
||||
packages/ui/src/
|
||||
components/ ← только CLI (не трогать под кейс)
|
||||
hooks/ ← registry hooks (use-mobile)
|
||||
lib/utils.ts ← cn()
|
||||
styles/globals.css ← только output shadcn CLI
|
||||
```
|
||||
|
||||
## Чеклист перед завершением задачи
|
||||
|
||||
- [ ] MCP shadcn: search + examples (+ add command при новых примитивах)
|
||||
- [ ] Решение есть в https://ui.shadcn.com/docs/components или /blocks
|
||||
- [ ] Компоненты добавлены через `pnpm dlx shadcn@latest add` из `apps/web`
|
||||
- [ ] Нет кастомного CSS и raw HTML-примитивов
|
||||
- [ ] Semantic tokens, `variant`/`size` вместо переопределения className
|
||||
- [ ] UI-импорты через `@cfdm/ui/components/*`
|
||||
- [ ] `pnpm --filter web build` без ошибок
|
||||
|
||||
## Язык
|
||||
|
||||
Ответы пользователю — русский. Commits — [`commit-messages-ru.mdc`](commit-messages-ru.mdc).
|
||||
@@ -0,0 +1,111 @@
|
||||
---
|
||||
description: Единые UI-паттерны web — shared components, docs workflow, матрица стандартизации
|
||||
globs: apps/web/**/*
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Frontend UI Patterns
|
||||
|
||||
См. также: [`frontend-shadcn.mdc`](frontend-shadcn.mdc), [`shadcn-mcp.mdc`](shadcn-mcp.mdc), [Components](https://ui.shadcn.com/docs/components), [Blocks](https://ui.shadcn.com/blocks).
|
||||
|
||||
## Docs workflow (обязательно)
|
||||
|
||||
0. Codegraph `codegraph_explore` — найти существующие shared/domain-компоненты
|
||||
1. Skill [`.agents/skills/shadcn/SKILL.md`](../.agents/skills/shadcn/SKILL.md) — component selection
|
||||
2. MCP `plugin-shadcn-shadcn` — search → examples → add command
|
||||
3. CLI: `cd apps/web && pnpm dlx shadcn@latest docs <component>` → сверить API с [Components](https://ui.shadcn.com/docs/components)
|
||||
4. Код по examples + docs API (только после совпадения MCP ↔ docs)
|
||||
5. Context7 — **только** TanStack Router/Query, Recharts (не shadcn primitives)
|
||||
6. MCP `get_audit_checklist` — перед merge
|
||||
7. Codegraph `codegraph_status` — Pending sync пустой
|
||||
|
||||
## Иерархия компонентов
|
||||
|
||||
```
|
||||
@cfdm/ui/components/* ← только CLI (packages/ui)
|
||||
apps/web/src/components/ ← shared + domain + layout
|
||||
page-shell.tsx ← обёртка страницы
|
||||
page-header.tsx
|
||||
empty-state.tsx
|
||||
query-state.tsx
|
||||
confirm-dialog.tsx
|
||||
data-table-card.tsx
|
||||
section-cards.tsx
|
||||
status-badge.tsx
|
||||
form-sheet.tsx ← Sheet + RHF FormProvider
|
||||
form-field.tsx ← Field + Controller + aria-invalid
|
||||
table-card.tsx ← Card + Table wrapper
|
||||
loading-button.tsx ← Button + Spinner + label swap
|
||||
section-cards-skeleton.tsx
|
||||
table-skeleton.tsx
|
||||
layout/ ← app-shell, site-header
|
||||
domain-* ← бизнес-компоненты
|
||||
```
|
||||
|
||||
## Матрица стандартизации
|
||||
|
||||
| Элемент | Shared | Primitive |
|
||||
|---------|--------|-----------|
|
||||
| Page wrapper | `PageShell` | — |
|
||||
| Page title | `PageHeader` | — |
|
||||
| Stat metrics | `SectionCards` | `Card` |
|
||||
| Data list | `DataTableCard` | `Table`, `InputGroup` |
|
||||
| Empty | `EmptyState` | `Empty` |
|
||||
| Loading / Error | `QueryState` | `Skeleton`, `Alert` |
|
||||
| Status | `StatusBadge` | `Badge` |
|
||||
| Create/Edit | `FormSheet` + `*-edit-sheet.tsx` | `Sheet`, `Field` |
|
||||
| Form field | `FormField` | `Field`, `Input`, `Select` |
|
||||
| Submit button | `LoadingButton` | `Button`, `Spinner` |
|
||||
| Table wrapper | `TableCard` | `Table`, `Card` |
|
||||
| Delete confirm | `ConfirmDialog` | `AlertDialog` |
|
||||
| List row | — | `Item variant="outline" size="sm"` |
|
||||
| Nav | `AppSidebar` | `Sidebar` |
|
||||
| Breadcrumbs | `SiteHeader` | `Breadcrumb` |
|
||||
| Dates | `lib/format.ts` | — |
|
||||
|
||||
## Overlay selection
|
||||
|
||||
| Сценарий | Компонент |
|
||||
|----------|-----------|
|
||||
| Create/edit форма | `Sheet` |
|
||||
| Destructive confirm | `AlertDialog` via `ConfirmDialog` |
|
||||
| Modal preview | `Dialog` |
|
||||
|
||||
## Block registry
|
||||
|
||||
| Зона | Block |
|
||||
|------|-------|
|
||||
| Shell | sidebar-07 |
|
||||
| Dashboard | dashboard-01 |
|
||||
| Login | login-03 |
|
||||
|
||||
## Spacing
|
||||
|
||||
```
|
||||
PageShell: gap-4 md:gap-6, px-4 lg:px-6 py-4 md:py-6
|
||||
Card grid: gap-4
|
||||
FieldGroup: gap-4
|
||||
Item list: gap-2
|
||||
Toolbar: gap-2
|
||||
```
|
||||
|
||||
**Запрещено:** `space-y-*`, raw colors (`bg-emerald-*`), custom empty divs, page-level Spinner.
|
||||
|
||||
## UX/UI 2026 (состояния данных)
|
||||
|
||||
Каждый блок: **default, hover, focus, disabled, empty, loading, error**.
|
||||
|
||||
- **Loading** — `Skeleton` с размерами финального контента (`QueryState skeleton={…}`), не Spinner на странице
|
||||
- **Empty** — `EmptyState` с CTA (кнопка создания)
|
||||
- **Zero-results** — отдельный empty с «Сбросить фильтр» (не «Создать»)
|
||||
- **Error** — `QueryState` + `onRetry` + иконка + текст
|
||||
- **Overflow** — `truncate`, `max-w-*`, `Tooltip`; `tabular-nums` для чисел
|
||||
- **Density** — таблицы `h-10 text-sm`; max 1 primary CTA на экран
|
||||
- **A11y** — `aria-invalid` на полях, `aria-label`/`sr-only` на icon-only кнопках, цвет не единственный сигнал статуса
|
||||
|
||||
## Button hierarchy (max 1 primary per screen)
|
||||
|
||||
1. `default` — главный CTA
|
||||
2. `outline` — вторичные действия
|
||||
3. `ghost` / `link` — навигация, cancel
|
||||
4. `destructive` — только с `ConfirmDialog`
|
||||
@@ -0,0 +1,113 @@
|
||||
---
|
||||
description: Gitflow Workflow Rules. These rules should be applied when performing git operations.
|
||||
globs: ["**/*"]
|
||||
alwaysApply: false
|
||||
---
|
||||
# Gitflow Workflow Rules
|
||||
|
||||
## Main Branches
|
||||
|
||||
### main (or master)
|
||||
- Contains production-ready code
|
||||
- Never commit directly to main
|
||||
- Only accepts merges from:
|
||||
- hotfix/* branches
|
||||
- release/* branches
|
||||
- Must be tagged with version number after each merge
|
||||
|
||||
### develop
|
||||
- Main development branch
|
||||
- Contains latest delivered development changes
|
||||
- Source branch for feature branches
|
||||
- Never commit directly to develop
|
||||
|
||||
## Supporting Branches
|
||||
|
||||
### feature/*
|
||||
- Branch from: develop
|
||||
- Merge back into: develop
|
||||
- Naming convention: feature/[issue-id]-descriptive-name
|
||||
- Example: feature/123-user-authentication
|
||||
- Must be up-to-date with develop before creating PR
|
||||
- Delete after merge
|
||||
|
||||
### release/*
|
||||
- Branch from: develop
|
||||
- Merge back into:
|
||||
- main
|
||||
- develop
|
||||
- Naming convention: release/vX.Y.Z
|
||||
- Example: release/v1.2.0
|
||||
- Only bug fixes, documentation, and release-oriented tasks
|
||||
- No new features
|
||||
- Delete after merge
|
||||
|
||||
### hotfix/*
|
||||
- Branch from: main
|
||||
- Merge back into:
|
||||
- main
|
||||
- develop
|
||||
- Naming convention: hotfix/vX.Y.Z
|
||||
- Example: hotfix/v1.2.1
|
||||
- Only for urgent production fixes
|
||||
- Delete after merge
|
||||
|
||||
## Commit Messages
|
||||
|
||||
- Format: `type(scope): description`
|
||||
- Types:
|
||||
- feat: New feature
|
||||
- fix: Bug fix
|
||||
- docs: Documentation changes
|
||||
- style: Formatting, missing semicolons, etc.
|
||||
- refactor: Code refactoring
|
||||
- test: Adding tests
|
||||
- chore: Maintenance tasks
|
||||
|
||||
## Version Control
|
||||
|
||||
### Semantic Versioning
|
||||
- MAJOR version for incompatible API changes
|
||||
- MINOR version for backwards-compatible functionality
|
||||
- PATCH version for backwards-compatible bug fixes
|
||||
|
||||
## Pull Request Rules
|
||||
|
||||
1. All changes must go through Pull Requests
|
||||
2. Required approvals: minimum 1
|
||||
3. CI checks must pass
|
||||
4. No direct commits to protected branches (main, develop)
|
||||
5. Branch must be up to date before merging
|
||||
6. Delete branch after merge
|
||||
|
||||
## Branch Protection Rules
|
||||
|
||||
### main & develop
|
||||
- Require pull request reviews
|
||||
- Require status checks to pass
|
||||
- Require branches to be up to date
|
||||
- Include administrators in restrictions
|
||||
- No force pushes
|
||||
- No deletions
|
||||
|
||||
## Release Process
|
||||
|
||||
1. Create release branch from develop
|
||||
2. Bump version numbers
|
||||
3. Fix any release-specific issues
|
||||
4. Create PR to main
|
||||
5. After merge to main:
|
||||
- Tag release
|
||||
- Merge back to develop
|
||||
- Delete release branch
|
||||
|
||||
## Hotfix Process
|
||||
|
||||
1. Create hotfix branch from main
|
||||
2. Fix the issue
|
||||
3. Bump patch version
|
||||
4. Create PR to main
|
||||
5. After merge to main:
|
||||
- Tag release
|
||||
- Merge back to develop
|
||||
- Delete hotfix branch
|
||||
@@ -1,26 +1,81 @@
|
||||
---
|
||||
description: Структура проекта vps-tracker и соглашения по именованию
|
||||
description: Структура vps-tracker — pnpm monorepo (apps/web, apps/api, packages/ui, packages/shared, packages/db)
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Структура проекта vps-tracker
|
||||
|
||||
## Папки
|
||||
pnpm workspaces monorepo. Frontend — shadcn/ui + TanStack Router/Query + TS. Backend — Fastify + Drizzle + better-sqlite3 + TS.
|
||||
|
||||
- `server/` — Express backend, SQLite (sql.js)
|
||||
- `src/` — React frontend (Vite)
|
||||
- `server/adapters/` — один адаптер на провайдера API (billmanager)
|
||||
- `server/routes/` — Express роутеры по сущностям
|
||||
- `server/db/` — схема, миграции, seed
|
||||
## Layout
|
||||
|
||||
```
|
||||
vps-tracker/
|
||||
├── apps/
|
||||
│ ├── web/ # Vite SPA (TSX) — TanStack Router + Query, shadcn/ui
|
||||
│ └── api/ # Fastify 5 API (TS) — @fastify/* + Drizzle
|
||||
├── packages/
|
||||
│ ├── ui/ # @cfdm/ui — shadcn primitives (output `shadcn add`)
|
||||
│ ├── shared/ # @cfdm/shared — Zod-схемы контрактов, общие типы
|
||||
│ └── db/ # @cfdm/db — Drizzle schema, repositories, миграции
|
||||
├── data/ # SQLite база (том Docker, gitignored)
|
||||
├── pnpm-workspace.yaml
|
||||
├── package.json
|
||||
└── tsconfig.base.json
|
||||
```
|
||||
|
||||
## apps/web
|
||||
|
||||
```
|
||||
apps/web/
|
||||
├── components.json # ui alias → @cfdm/ui/components
|
||||
├── vite.config.ts # React + TanStack Router plugin, proxy /api → apps/api
|
||||
├── tsconfig.json
|
||||
└── src/
|
||||
├── main.tsx # QueryClientProvider, createRouter, import '@cfdm/ui/globals.css'
|
||||
├── routes/ # file-based routes (__root.tsx, _auth/...)
|
||||
├── queries/ # queryOptions + key factories по сущностям
|
||||
├── components/ # shared + layout + domain (blocks)
|
||||
└── lib/ # api-client, queryClient, router, schemas
|
||||
```
|
||||
|
||||
## apps/api
|
||||
|
||||
```
|
||||
apps/api/
|
||||
└── src/
|
||||
├── index.ts # buildApp()
|
||||
├── config.ts # env через Zod
|
||||
├── routes/ # тонкие Fastify plugins
|
||||
├── services/ # бизнес-логика + адаптеры (billmanager/*)
|
||||
└── plugins/ # @fastify/* registration
|
||||
```
|
||||
|
||||
## packages/db
|
||||
|
||||
```
|
||||
packages/db/src/
|
||||
├── schema/ # Drizzle tables по сущностям
|
||||
├── repositories/ # typed queries (inArray, JOIN, transaction)
|
||||
└── migrations/ # drizzle-kit generate/migrate
|
||||
```
|
||||
|
||||
## Именование
|
||||
|
||||
- Файлы: kebab-case (provider-accounts.js, row-mappers.js)
|
||||
- Роуты: `/api/vps`, `/api/provider-accounts`, `/api/sync/:accountId`
|
||||
- Файлы: kebab-case (`provider-accounts.ts`, `row-mappers.ts`)
|
||||
- Компоненты: PascalCase (`PageHeader.tsx`)
|
||||
- Роуты API: `/api/vps`, `/api/provider-accounts`, `/api/sync/:accountId`
|
||||
- ID записей: `vps-bm-{accountId}-{externalId}`, `pay-bm-{accountId}-{externalId}`
|
||||
|
||||
## Barrel exports
|
||||
|
||||
Модули с несколькими файлами экспортируют через `index.js`:
|
||||
- `server/adapters/billmanager/index.js` — testConnection, syncFromBillmanager, fetchDashboardInfo
|
||||
- `server/db/index.js` — initDb, getDb, saveDb
|
||||
- `packages/ui` — `@cfdm/ui/components/*`, `@cfdm/ui/lib/utils`, `@cfdm/ui/hooks/*`, `@cfdm/ui/globals.css`
|
||||
- `packages/shared` — `@cfdm/shared/contracts/*` (Zod), `@cfdm/shared/types/*`
|
||||
- `packages/db` — `@cfdm/db/schema`, `@cfdm/db/repositories/*`
|
||||
- `apps/api/src/services/billmanager/index.ts` — `testConnection`, `syncFromBillmanager`, `fetchDashboardInfo`
|
||||
|
||||
## Скоупы правил
|
||||
|
||||
- Frontend (`apps/web`, `packages/ui`) — [`frontend-monorepo.mdc`](frontend-monorepo.mdc), [`frontend-shadcn.mdc`](frontend-shadcn.mdc), [`frontend-ui-patterns.mdc`](frontend-ui-patterns.mdc), [`vite-tanstack-frontend.mdc`](vite-tanstack-frontend.mdc), [`shadcn-mcp.mdc`](shadcn-mcp.mdc), [`shadcn-ui-production.mdc`](shadcn-ui-production.mdc)
|
||||
- Backend (`apps/api`, `packages/db`, `packages/shared`) — [`backend-fastify.mdc`](backend-fastify.mdc), [`backend-drizzle.mdc`](backend-drizzle.mdc), [`backend-mcp.mdc`](backend-mcp.mdc), [`backend-testing.mdc`](backend-testing.mdc), [`backend-api-ui.mdc`](backend-api-ui.mdc), [`sqlite.mdc`](sqlite.mdc)
|
||||
- API + UI-связка — [`backend-api-ui.mdc`](backend-api-ui.mdc)
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
description: Паттерны для Express, db, adapters
|
||||
globs: server/**/*.js
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Server conventions
|
||||
|
||||
## Express
|
||||
|
||||
- Роутеры в `routes/`, подключаются в `index.js` через `app.use('/api/...', router)`
|
||||
- Ошибки: `res.status(500).json({ error: err.message })`
|
||||
- 404: `res.status(404).json({ error: 'Not found' })`
|
||||
|
||||
## Database
|
||||
|
||||
- Доступ через `getDb()` — обёртка с `prepare().all()`, `prepare().get()`, `run()`
|
||||
- После `run()` вызывается `saveDb()` автоматически
|
||||
- Миграции в `db/migrations.js`, добавляют колонки через ALTER TABLE
|
||||
|
||||
## Adapters
|
||||
|
||||
- Один провайдер = папка в `adapters/` (billmanager)
|
||||
- Разделение: client (HTTP), parsers, mappers, operations, sync
|
||||
- Публичный API через `index.js`
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
description: ВСЕГДА использовать MCP-плагин shadcn UI перед любым UI-кодом
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# shadcn MCP — обязательно
|
||||
|
||||
Перед **любой** задачей с UI (новый экран, компонент, стили, рефакторинг внешнего вида) — **сначала MCP** `plugin-shadcn-shadcn`, не память и не веб-поиск.
|
||||
|
||||
CLI и docs — **после** MCP, по команде из `get_add_command_for_items`.
|
||||
|
||||
## Порядок (строго)
|
||||
|
||||
0. **Codegraph** `codegraph_explore` — найти существующие реализации и shared-обёртки (один вызов перед правками)
|
||||
1. **`get_project_registries`** — какие registry доступны в проекте
|
||||
2. **`search_items_in_registries`** — компонент, block, example (`query`: `"card"`, `"tabs demo"`, `"dashboard"`, `"scroll-area"`)
|
||||
3. **`get_item_examples_from_registries`** — полный код примера перед написанием JSX
|
||||
4. **`get_add_command_for_items`** — точная CLI-команда `pnpm dlx shadcn@latest add ...`
|
||||
5. Выполнить add из `apps/web` (см. [`frontend-monorepo.mdc`](frontend-monorepo.mdc))
|
||||
6. **CLI docs (обязательно):** `cd apps/web && pnpm dlx shadcn@latest docs <component>` — сверить API/props с [ui.shadcn.com/docs/components](https://ui.shadcn.com/docs/components)
|
||||
7. Сверить examples из MCP с API из docs CLI — реализовать только после совпадения
|
||||
8. Адаптировать пример под TanStack Router / Query → `apps/web/src/`
|
||||
9. **Context7** — только TanStack / Recharts / не-shadcn (не заменяет шаги 1–8 для примитивов)
|
||||
10. **`get_audit_checklist`** — перед merge PR
|
||||
11. **Codegraph** `codegraph_status` — Pending sync пустой после правок
|
||||
|
||||
## Когда вызывать MCP
|
||||
|
||||
| Задача | MCP |
|
||||
|--------|-----|
|
||||
| Новая страница / layout | `search` → `types: ["block"]` → examples → add block |
|
||||
| Нет примитива в `@cfdm/ui` | `search` → `get_add_command_for_items` → add |
|
||||
| Сомнение в API/props | `get_item_examples_from_registries` |
|
||||
| Ревью UI перед сдачей | `get_audit_checklist` |
|
||||
|
||||
## Запрещено
|
||||
|
||||
- Писать UI по памяти, не проверив MCP
|
||||
- Копипаст с ui.shadcn.com без examples/add из MCP
|
||||
- Самописные примитивы, если есть item в registry
|
||||
- Пропускать MCP «потому что компонент простой»
|
||||
|
||||
## Сервер и инструменты
|
||||
|
||||
- **MCP server:** `plugin-shadcn-shadcn`
|
||||
- **Инструменты:** `get_project_registries`, `search_items_in_registries`, `get_item_examples_from_registries`, `get_add_command_for_items`, `view_items_in_registries`, `list_items_in_registries`, `get_audit_checklist`
|
||||
- Перед вызовом — прочитать schema в `mcps/plugin-shadcn-shadcn/tools/`
|
||||
|
||||
Связанные правила: [`shadcn-ui-production.mdc`](shadcn-ui-production.mdc), [`frontend-shadcn.mdc`](frontend-shadcn.mdc).
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
description: shadcn/ui — глобальные UI-принципы проекта; frontend см. frontend-shadcn.mdc
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# shadcn/ui — правила проекта
|
||||
|
||||
UI строится **исключительно** по [shadcn/ui](https://ui.shadcn.com/docs/installation): [Components](https://ui.shadcn.com/docs/components), [Blocks](https://ui.shadcn.com/blocks), [Monorepo](https://ui.shadcn.com/docs/monorepo).
|
||||
|
||||
**Первый шаг любой UI-задачи — MCP `plugin-shadcn-shadcn`** (см. [`shadcn-mcp.mdc`](shadcn-mcp.mdc)): search → examples → add command → CLI.
|
||||
|
||||
## Разработка frontend
|
||||
|
||||
**Все правила frontend** — в [`frontend-shadcn.mdc`](frontend-shadcn.mdc), [`frontend-ui-patterns.mdc`](frontend-ui-patterns.mdc) и [`frontend-monorepo.mdc`](frontend-monorepo.mdc) (globs: `apps/web/**`, `packages/ui/**`).
|
||||
|
||||
Кратко: docs → CLI из `apps/web` → Block → композиция → `pnpm --filter web build`. Кастомный CSS и самописные примитивы **запрещены**.
|
||||
|
||||
## Стек
|
||||
|
||||
- Monorepo: `apps/web` + `packages/ui` (`@cfdm/ui`), pnpm workspaces
|
||||
- Vite + TanStack Router/Query + shadcn **base-nova**
|
||||
- Конфиг: [`apps/web/components.json`](apps/web/components.json), [`packages/ui/components.json`](packages/ui/components.json)
|
||||
- Тема: `pnpm dlx shadcn@latest apply b2fA --only theme -y` — единственный способ менять `packages/ui/src/styles/globals.css`
|
||||
|
||||
## Backend → UI
|
||||
|
||||
При правках API с экранами: [`backend-api-ui.mdc`](backend-api-ui.mdc). Backend: `apps/api` (Fastify + Drizzle).
|
||||
|
||||
## Устаревший стек (запрещён в apps/web)
|
||||
|
||||
Проект мигрирует с Tabler-стека на shadcn/ui. **Не использовать**:
|
||||
|
||||
- `@tabler/core` и `@tabler/core/dist/css/tabler.min.css` — заменить на `@cfdm/ui/globals.css`
|
||||
- `@tabler/icons-react` — иконки только `lucide-react`
|
||||
- `chart.js` — графики только `recharts` через shadcn `Chart`/`ChartContainer`
|
||||
- `react-router-dom` — роутинг только TanStack Router (`createFileRoute`, file-based routes)
|
||||
- Bootstrap/Tabler utility-классы (`page`, `navbar-vertical`, `nav-link`, `container-tight`, `spinner-border`, `d-lg-none`, `page-wrapper`) — layout через Tailwind + shadcn blocks (sidebar-07)
|
||||
|
||||
## Язык
|
||||
|
||||
Русский. Commits: [`commit-messages-ru.mdc`](commit-messages-ru.mdc).
|
||||
@@ -0,0 +1,188 @@
|
||||
---
|
||||
description: Definitive guidelines for writing robust, performant, and secure SQLite code. Focuses on schema design, query optimization, and transaction management.
|
||||
globs: **/*
|
||||
---
|
||||
# sqlite Best Practices
|
||||
|
||||
> В проекте используется **better-sqlite3** через Drizzle (`packages/db`). WASM-`sql.js` выводится из эксплуатации. См. [`backend-drizzle.mdc`](backend-drizzle.mdc).
|
||||
|
||||
SQLite is the go-to embedded SQL engine for local, reliable storage. Adhere to these rules to ensure your SQLite code is maintainable, performant, and secure.
|
||||
|
||||
## 1. Data Modeling & Schema Design
|
||||
|
||||
Design your schema for integrity and performance from day one.
|
||||
|
||||
* **Primary Keys**: Always use `INTEGER PRIMARY KEY AUTOINCREMENT` for ID columns. This optimizes `rowid` lookups and simplifies ID generation.
|
||||
* ❌ BAD:
|
||||
```sql
|
||||
CREATE TABLE users (
|
||||
id TEXT PRIMARY KEY, -- Manual UUIDs or similar
|
||||
name TEXT NOT NULL
|
||||
);
|
||||
```
|
||||
* ✅ GOOD:
|
||||
```sql
|
||||
CREATE TABLE users (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
name TEXT NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
* **Data Types & Constraints**: Declare appropriate data types and enforce integrity with `NOT NULL`, `UNIQUE`, and `FOREIGN KEY` constraints.
|
||||
* ❌ BAD:
|
||||
```sql
|
||||
CREATE TABLE products (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
name TEXT, -- Allows NULL, no uniqueness
|
||||
price REAL
|
||||
);
|
||||
```
|
||||
* ✅ GOOD:
|
||||
```sql
|
||||
CREATE TABLE products (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
name TEXT NOT NULL UNIQUE,
|
||||
price REAL NOT NULL,
|
||||
stock INTEGER DEFAULT 0,
|
||||
category_id INTEGER,
|
||||
FOREIGN KEY (category_id) REFERENCES categories(id) ON DELETE SET NULL
|
||||
);
|
||||
```
|
||||
|
||||
* **Naming Conventions**: Use `lower_case_snake_case` for all table, column, and index names. Avoid SQLite keywords as identifiers.
|
||||
* ❌ BAD: `CREATE TABLE My_Users ( UserId INTEGER PRIMARY KEY );`
|
||||
* ✅ GOOD: `CREATE TABLE my_users ( user_id INTEGER PRIMARY KEY );`
|
||||
|
||||
## 2. Performance Considerations
|
||||
|
||||
Optimize for speed by minimizing I/O and leveraging the SQLite engine.
|
||||
|
||||
* **Enable WAL Mode**: Always enable Write-Ahead Logging for better concurrency and write performance.
|
||||
* ❌ BAD: Default journal mode (`DELETE`).
|
||||
* ✅ GOOD (at database open or once):
|
||||
```sql
|
||||
PRAGMA journal_mode = WAL;
|
||||
```
|
||||
|
||||
* **Relax Synchronous Mode**: When using WAL, set `synchronous` to `NORMAL` for faster commits, accepting minimal risk of data loss on power failure (not app crash).
|
||||
* ❌ BAD: Default `synchronous = FULL`.
|
||||
* ✅ GOOD (at database open or once):
|
||||
```sql
|
||||
PRAGMA synchronous = NORMAL;
|
||||
```
|
||||
|
||||
* **Indexes**: Create indexes on columns frequently used in `WHERE`, `ORDER BY`, `GROUP BY`, or `JOIN` clauses. Avoid over-indexing.
|
||||
* ❌ BAD:
|
||||
```sql
|
||||
SELECT * FROM users WHERE email = '[email protected]'; -- No index on email
|
||||
```
|
||||
* ✅ GOOD:
|
||||
```sql
|
||||
CREATE INDEX idx_users_email ON users(email);
|
||||
SELECT id, name FROM users WHERE email = '[email protected]';
|
||||
```
|
||||
* **Multi-column Indexes**: For queries filtering/sorting on multiple columns, create a multi-column index matching the query order.
|
||||
```sql
|
||||
CREATE INDEX idx_products_category_price ON products(category_id, price);
|
||||
SELECT * FROM products WHERE category_id = 1 ORDER BY price DESC;
|
||||
```
|
||||
|
||||
* **Query Optimization**: Select only the columns you need. Push filtering, sorting, and aggregation into SQL.
|
||||
* ❌ BAD:
|
||||
```sql
|
||||
SELECT * FROM products; -- Fetch all columns
|
||||
-- Then filter/sort in application code
|
||||
```
|
||||
* ✅ GOOD:
|
||||
```sql
|
||||
SELECT id, name, price FROM products WHERE stock > 0 ORDER BY price ASC LIMIT 10;
|
||||
```
|
||||
|
||||
## 3. Transactions & Concurrency
|
||||
|
||||
Ensure data consistency and improve write performance with explicit transactions.
|
||||
|
||||
* **Wrap Writes in Transactions**: Group multiple `INSERT`, `UPDATE`, `DELETE` operations within a single transaction. This significantly reduces disk I/O.
|
||||
* ❌ BAD:
|
||||
```sql
|
||||
INSERT INTO logs (action) VALUES ('User created');
|
||||
INSERT INTO users (name) VALUES ('New User');
|
||||
INSERT INTO logs (action) VALUES ('User name updated');
|
||||
UPDATE users SET name = 'Updated User' WHERE id = 1;
|
||||
```
|
||||
* ✅ GOOD:
|
||||
```sql
|
||||
BEGIN;
|
||||
INSERT INTO logs (action) VALUES ('User created');
|
||||
INSERT INTO users (name) VALUES ('New User');
|
||||
INSERT INTO logs (action) VALUES ('User name updated');
|
||||
UPDATE users SET name = 'Updated User' WHERE id = 1;
|
||||
COMMIT;
|
||||
```
|
||||
|
||||
* **Error Handling**: Use `ROLLBACK` to revert all changes if any operation within a transaction fails.
|
||||
* ✅ GOOD:
|
||||
```sql
|
||||
BEGIN;
|
||||
-- Perform operations
|
||||
INSERT INTO users (name) VALUES ('Valid User');
|
||||
INSERT INTO users (name) VALUES (NULL); -- This will fail due to NOT NULL
|
||||
-- If an error occurs, catch it and:
|
||||
ROLLBACK;
|
||||
-- Else:
|
||||
COMMIT;
|
||||
```
|
||||
|
||||
## 4. Security Best Practices
|
||||
|
||||
Prevent common vulnerabilities like SQL injection.
|
||||
|
||||
* **Prepared Statements**: Always use prepared statements with bound parameters. NEVER concatenate user input directly into SQL queries.
|
||||
* ❌ BAD:
|
||||
```sql
|
||||
String name = userInput.getName();
|
||||
String sql = "INSERT INTO users (name) VALUES ('" + name + "');"; // SQL Injection risk!
|
||||
```
|
||||
* ✅ GOOD (using a typical API pattern):
|
||||
```sql
|
||||
PreparedStatement stmt = connection.prepareStatement("INSERT INTO users (name) VALUES (?);");
|
||||
stmt.setString(1, userInput.getName());
|
||||
stmt.executeUpdate();
|
||||
```
|
||||
|
||||
* **Enable Foreign Key Enforcement**: Always enable foreign key constraints at runtime. SQLite defaults to `OFF` for backward compatibility.
|
||||
* ❌ BAD: Forgetting to enable foreign keys, leading to orphaned records.
|
||||
* ✅ GOOD (at database open or once per connection):
|
||||
```sql
|
||||
PRAGMA foreign_keys = ON;
|
||||
```
|
||||
|
||||
* **File Permissions**: Store database files in write-protected directories and set restrictive file permissions to limit unauthorized access. This is OS-specific but critical.
|
||||
|
||||
## 5. Common Pitfalls & Gotchas
|
||||
|
||||
Avoid these common mistakes that lead to bugs and performance issues.
|
||||
|
||||
* **Forgetting `PRAGMA foreign_keys = ON;`**: This is the most common pitfall. Always enable it.
|
||||
* **Selecting `*`**: Only retrieve the columns you actually need.
|
||||
* **Application-level Filtering/Sorting**: Delegate these operations to SQL for better performance, especially on large datasets.
|
||||
* **Not Using Transactions**: Leads to slow writes and potential data inconsistencies.
|
||||
* **Using SQLite for High-Concurrency Writes**: SQLite is a single-writer database. If multiple processes need to write concurrently, consider a client-server RDBMS.
|
||||
|
||||
## 6. Testing Approaches
|
||||
|
||||
Ensure your data access logic is robust and correct.
|
||||
|
||||
* **In-Memory Databases**: Use `:memory:` databases for fast, isolated unit and integration tests of your data access layer.
|
||||
* ✅ GOOD (example in Python, similar patterns exist in other languages):
|
||||
```python
|
||||
import sqlite3
|
||||
conn = sqlite3.connect(':memory:')
|
||||
cursor = conn.cursor()
|
||||
cursor.execute("CREATE TABLE test_data (id INTEGER PRIMARY KEY, value TEXT)")
|
||||
# ... run tests ...
|
||||
conn.close() # Database vanishes
|
||||
```
|
||||
|
||||
* **Seed Data**: Create consistent, reproducible test data for your tests.
|
||||
* **Mocking**: For higher-level tests, mock your database interactions to focus on business logic.
|
||||
@@ -0,0 +1,120 @@
|
||||
---
|
||||
description: Vite + TanStack Router v1 + TanStack Query v5 — routing, loaders, queries, mutations
|
||||
globs: apps/web/**/*.{tsx,ts}
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Vite + TanStack Router + Query
|
||||
|
||||
Фронтенд: **Vite SPA**, не Next.js. Нет Server Components, App Router, `'use client'`.
|
||||
|
||||
## Структура
|
||||
|
||||
```
|
||||
apps/web/src/
|
||||
routes/ # file-based routes (__root.tsx, _auth/, ...)
|
||||
queries/ # queryOptions factories + key factories
|
||||
lib/ # api-client, queryClient, auth, schemas
|
||||
components/ # domain + layout (UI primitives → @cfdm/ui)
|
||||
main.tsx
|
||||
```
|
||||
|
||||
## Архитектура
|
||||
|
||||
- **Router** — маршрутизация, URL state, navigation, loaders
|
||||
- **Query** — server state, cache, mutations
|
||||
- **Loader** — `queryClient.ensureQueryData()` до рендера → без спиннеров на route data
|
||||
- **Компоненты** — UI; данные из Query cache
|
||||
|
||||
## QueryClient + Router
|
||||
|
||||
```ts
|
||||
// lib/queryClient.ts
|
||||
export const queryClient = new QueryClient({
|
||||
defaultOptions: { queries: { staleTime: 60_000 } },
|
||||
})
|
||||
|
||||
// lib/router.ts
|
||||
export const router = createRouter({
|
||||
routeTree,
|
||||
context: { queryClient },
|
||||
defaultPreload: 'intent',
|
||||
})
|
||||
|
||||
declare module '@tanstack/react-router' {
|
||||
interface Register { router: typeof router }
|
||||
}
|
||||
```
|
||||
|
||||
## Query definitions
|
||||
|
||||
- `queryOptions` factories в `queries/`, не inline в компонентах
|
||||
- Key factories: `all` → `lists` / `details` → `list(filters)` / `detail(id)`
|
||||
|
||||
```ts
|
||||
export const serviceKeys = {
|
||||
all: ['services'] as const,
|
||||
list: () => [...serviceKeys.all, 'list'] as const,
|
||||
}
|
||||
|
||||
export const servicesQueryOptions = () =>
|
||||
queryOptions({
|
||||
queryKey: serviceKeys.list(),
|
||||
queryFn: () => api.get('/api/v1/services'),
|
||||
})
|
||||
```
|
||||
|
||||
## Loader + component
|
||||
|
||||
```tsx
|
||||
export const Route = createFileRoute('/_auth/services')({
|
||||
loader: ({ context: { queryClient } }) =>
|
||||
queryClient.ensureQueryData(servicesQueryOptions()),
|
||||
component: ServicesPage,
|
||||
})
|
||||
|
||||
function ServicesPage() {
|
||||
const { data } = useQuery(servicesQueryOptions()) // из cache loader
|
||||
return ...
|
||||
}
|
||||
```
|
||||
|
||||
## Search params
|
||||
|
||||
- Zod + `validateSearch`; доступ через `Route.useSearch()`
|
||||
- Search params = source of truth для фильтров/пагинации
|
||||
- Передавать в `queryOptions` для query key и fetcher
|
||||
|
||||
## Mutations
|
||||
|
||||
```ts
|
||||
onSuccess: (newItem) => {
|
||||
queryClient.setQueryData(keys.detail(newItem.id), newItem)
|
||||
queryClient.invalidateQueries({ queryKey: keys.lists() })
|
||||
}
|
||||
```
|
||||
|
||||
- `setQueryData` + `invalidateQueries`, не только invalidate
|
||||
- Навигация после create — когда cache уже тёплый
|
||||
|
||||
## Routing
|
||||
|
||||
- `createFileRoute` для file-based routes
|
||||
- `<Link>` для внутренней навигации, не `<a href>`
|
||||
- Pathless layouts: `_auth/` для protected routes
|
||||
- Auth guard в `beforeLoad` pathless route
|
||||
|
||||
## Запреты
|
||||
|
||||
- `useEffect` для fetch данных — только loader / `useQuery`
|
||||
- Inline `queryKey` в компонентах — только factories из `queries/`
|
||||
- `useQuery` с позиционными аргументами (v5 — только options object)
|
||||
- `window.location` для search params
|
||||
|
||||
## Prefetch
|
||||
|
||||
`onMouseEnter` на `<Link>` → `queryClient.prefetchQuery(detailOptions(id))`
|
||||
|
||||
## DevTools
|
||||
|
||||
Только в dev: `TanStackRouterDevtools`, `ReactQueryDevtools`
|
||||
@@ -0,0 +1,251 @@
|
||||
---
|
||||
description: Opinionated best practices for fast, reliable Vitest unit and integration tests in JS/TS projects.
|
||||
globs: **/*.{js,ts,jsx,tsx}
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Vitest Best Practices
|
||||
|
||||
Vitest is the definitive testing framework for our Vite-powered projects. It offers a fast, Jest-compatible API with deep integration into the Vite ecosystem. Adhering to these guidelines ensures our tests are robust, performant, and easy to maintain.
|
||||
|
||||
## 1. Code Organization & Naming
|
||||
|
||||
**Always co-locate test files with their source.** This improves discoverability and ensures tests are updated alongside their implementation.
|
||||
|
||||
* **File Naming**: Use `*.test.{ts,tsx,js,jsx}`.
|
||||
* **Location**: Place test files directly next to the component or module they test.
|
||||
|
||||
❌ BAD:
|
||||
```
|
||||
// src/components/Button/Button.tsx
|
||||
// tests/components/Button.test.tsx
|
||||
```
|
||||
|
||||
✅ GOOD:
|
||||
```typescript
|
||||
// src/components/Button/Button.tsx
|
||||
// src/components/Button/Button.test.tsx
|
||||
```
|
||||
|
||||
## 2. Test Structure & Isolation
|
||||
|
||||
**Organize tests logically using `describe` and `it` (or `test`) blocks.** Ensure each test is isolated and deterministic.
|
||||
|
||||
* **`describe`**: Group related tests into suites.
|
||||
* **`it` / `test`**: Define individual test cases. Prefer `it` for consistency with Jest.
|
||||
* **Hooks (`beforeEach`, `afterEach`)**: Use these for setup and teardown to ensure test isolation.
|
||||
|
||||
❌ BAD: (Shared state, no cleanup)
|
||||
```typescript
|
||||
let user;
|
||||
test('creates user', () => {
|
||||
user = createUser();
|
||||
expect(user).toBeDefined();
|
||||
});
|
||||
test('updates user', () => { // Depends on previous test
|
||||
user.name = 'New Name';
|
||||
expect(user.name).toBe('New Name');
|
||||
});
|
||||
```
|
||||
|
||||
✅ GOOD: (Isolated tests with hooks)
|
||||
```typescript
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||
import { createUser, deleteUser } from './user-service';
|
||||
|
||||
describe('User Service', () => {
|
||||
let user;
|
||||
|
||||
beforeEach(() => {
|
||||
user = createUser(); // Create a fresh user for each test
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
deleteUser(user.id); // Clean up after each test
|
||||
});
|
||||
|
||||
it('should create a user', () => {
|
||||
expect(user).toBeDefined();
|
||||
expect(user.id).toBeTypeOf('string');
|
||||
});
|
||||
|
||||
it('should update a user', () => {
|
||||
user.name = 'Jane Doe';
|
||||
expect(user.name).toBe('Jane Doe');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## 3. Asynchronous Testing with `vi.waitFor`
|
||||
|
||||
**Always use `vi.waitFor` for polling conditions in asynchronous tests.** Avoid arbitrary `setTimeout` calls or manual polling loops. `vi.waitFor` is designed for reliable synchronization.
|
||||
|
||||
❌ BAD: (Flaky, relies on arbitrary timeout)
|
||||
```typescript
|
||||
test('data loads after delay', async () => {
|
||||
let data = null;
|
||||
fetchData().then(res => (data = res));
|
||||
await new Promise(resolve => setTimeout(resolve, 100)); // Arbitrary wait
|
||||
expect(data).toEqual('some data');
|
||||
});
|
||||
```
|
||||
|
||||
✅ GOOD: (Reliable polling with `vi.waitFor`)
|
||||
```typescript
|
||||
import { it, expect, vi } from 'vitest';
|
||||
import { fetchData } from './api'; // Assume fetchData returns a Promise
|
||||
|
||||
it('should load data after delay', async () => {
|
||||
let data = null;
|
||||
fetchData().then(res => (data = res));
|
||||
|
||||
// Polls until data is not null, with a 2-second timeout
|
||||
await vi.waitFor(() => expect(data).not.toBeNull(), { timeout: 2000 });
|
||||
|
||||
expect(data).toEqual('some data');
|
||||
});
|
||||
```
|
||||
|
||||
## 4. Mocking Strategies
|
||||
|
||||
**Leverage Vitest's `vi` API for all mocking.** This provides Jest-compatible syntax and seamless integration. Always clean up mocks after each test.
|
||||
|
||||
* **`vi.fn()`**: Mock individual functions.
|
||||
* **`vi.spyOn()`**: Spy on existing object methods.
|
||||
* **`vi.mock()`**: Mock entire modules.
|
||||
|
||||
### Function Mocking
|
||||
|
||||
❌ BAD: (Manual mock, no easy reset)
|
||||
```typescript
|
||||
const originalFetch = global.fetch;
|
||||
global.fetch = () => Promise.resolve({ json: () => ({ id: 1 }) });
|
||||
// ... test ...
|
||||
global.fetch = originalFetch; // Easy to forget cleanup
|
||||
```
|
||||
|
||||
✅ GOOD: (Using `vi.fn` with `afterEach` cleanup)
|
||||
```typescript
|
||||
import { it, expect, vi, afterEach } from 'vitest';
|
||||
import { getUser } from './user-api';
|
||||
|
||||
// Mock the module containing fetchUser
|
||||
vi.mock('./user-api', async (importOriginal) => {
|
||||
const mod = await importOriginal();
|
||||
return {
|
||||
...mod,
|
||||
fetchUser: vi.fn(), // Mock specific function within the module
|
||||
};
|
||||
});
|
||||
|
||||
// Import the mocked function after vi.mock
|
||||
import { fetchUser } from './user-api';
|
||||
|
||||
afterEach(() => {
|
||||
vi.clearAllMocks(); // Clear mock calls after each test to prevent state leakage
|
||||
});
|
||||
|
||||
it('should fetch user data', async () => {
|
||||
fetchUser.mockResolvedValueOnce({ id: 1, name: 'Test User' });
|
||||
const user = await getUser(1);
|
||||
expect(fetchUser).toHaveBeenCalledWith(1);
|
||||
expect(user.name).toBe('Test User');
|
||||
});
|
||||
```
|
||||
|
||||
### Module Mocking
|
||||
|
||||
**Mock modules at the top of the file.** This ensures the mock is applied before the module under test imports it.
|
||||
|
||||
✅ GOOD: (Module mock before imports)
|
||||
```typescript
|
||||
import { vi, it, expect } from 'vitest';
|
||||
|
||||
// Mock the entire 'lodash' module to control its behavior
|
||||
vi.mock('lodash', () => ({
|
||||
debounce: vi.fn((fn) => fn), // Mock debounce to execute immediately
|
||||
}));
|
||||
|
||||
import { debounce } from 'lodash'; // Import the mocked debounce
|
||||
import { saveInput } from './input-handler'; // Module using debounce
|
||||
|
||||
it('should call save function without debounce delay', () => {
|
||||
saveInput('test');
|
||||
expect(debounce).toHaveBeenCalledOnce();
|
||||
});
|
||||
```
|
||||
|
||||
## 5. DOM Environment & Component Testing
|
||||
|
||||
**Use `happy-dom` for lightweight DOM environments.** It's generally faster and sufficient for most component tests. Switch to `jsdom` only if specific browser APIs are missing in `happy-dom`.
|
||||
|
||||
* Configure in `vite.config.ts` or `vitest.config.ts`.
|
||||
|
||||
✅ GOOD: (Configuring `happy-dom`)
|
||||
```typescript
|
||||
// vite.config.ts or vitest.config.ts
|
||||
import { defineConfig } from 'vitest/config';
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
environment: 'happy-dom', // Use happy-dom for faster DOM mocking
|
||||
globals: true, // Auto-import test APIs globally (e.g., describe, it, expect)
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## 6. Performance & Concurrent Tests
|
||||
|
||||
**Utilize `.concurrent` for tests that can run in parallel.** This significantly speeds up test suites where tests are independent.
|
||||
|
||||
* Use `it.concurrent` for individual tests.
|
||||
* Use `describe.concurrent` for entire suites.
|
||||
* **Important**: When using `.concurrent`, always destructure `expect` from the test context to avoid issues with snapshot and assertion tracking.
|
||||
|
||||
❌ BAD: (Sequential tests, slow)
|
||||
```typescript
|
||||
describe('My Feature', () => {
|
||||
it('test A', async () => { /* ... */ });
|
||||
it('test B', async () => { /* ... */ });
|
||||
});
|
||||
```
|
||||
|
||||
✅ GOOD: (Concurrent tests, faster)
|
||||
```typescript
|
||||
import { describe, it } from 'vitest';
|
||||
|
||||
describe.concurrent('My Feature', () => {
|
||||
it('test A', async ({ expect }) => { // Destructure expect for concurrent tests
|
||||
expect(1).toBe(1);
|
||||
});
|
||||
|
||||
it.concurrent('test B', async ({ expect }) => { // Destructure expect
|
||||
expect(2).toBe(2);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## 7. Code Coverage
|
||||
|
||||
**Enable V8-based code coverage.** It offers near-zero overhead and integrates seamlessly.
|
||||
|
||||
* Add `coverage` configuration to `vite.config.ts` or `vitest.config.ts`.
|
||||
* Run with `vitest run --coverage`.
|
||||
|
||||
✅ GOOD: (V8 coverage configuration)
|
||||
```typescript
|
||||
// vite.config.ts or vitest.config.ts
|
||||
import { defineConfig } from 'vitest/config';
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
environment: 'happy-dom',
|
||||
globals: true,
|
||||
coverage: {
|
||||
provider: 'v8', // Use V8 for native, fast coverage
|
||||
reporter: ['text', 'json', 'html'], // Output formats for reports
|
||||
exclude: ['node_modules/', 'dist/', '.eslintrc.cjs'], // Exclude common directories from coverage
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"plugins": {
|
||||
"cloudflare": {
|
||||
"enabled": true
|
||||
},
|
||||
"claude-plugins-official/typescript-lsp": {
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user