gendesign/.claude/rules/frontend.md

paths
frontend/**/*.{ts,tsx,jsx,js}

Frontend conventions — Next.js 15 / React 19 / TypeScript 5

Critical

• App router only — НЕ pages/ router
• TanStack Query для data-fetching — никакого useEffect для HTTP запросов
• TS strict — никаких any; для unknown shape → unknown + narrow
• TanStack Query keys — массивы: ["scrape-logs", scraperType, runIdFilter]
• Tailwind 4 утилитарные классы; inline styles только для динамических значений
• Server / Client components разделены явно — "use client" в начале client'а

XSS prevention (recurring bug class)

При рендере markdown / user-supplied content:

• URL validation: allowlist schemes перед инъекцией в href= / src=:
  • ✅ https://, http://, /, #, mailto:
  • ❌ javascript:, data:, vbscript:, file: → fallback #
• Pattern: helper safeUrl(url: string): string перед записью в attr

Reference: vault Bug_RenderMarkdown_JavascriptUrl_May14 (renderMarkdown.ts:safeUrl).

After backend schema change

cd frontend && npm run codegen

Обновляет src/types/openapi.ts из live OpenAPI. Без этого frontend build упадёт на missing types.

package.json + lockfile sync (CRITICAL — deploy aborts on mismatch)

Если меняешь frontend/package.json (add/remove/bump dep) — обязан также:

cd frontend && npm install --legacy-peer-deps --no-audit --no-fund

И закоммитить обновлённый frontend/package-lock.json в той же ветке.

Why: frontend/Dockerfile использует npm ci --legacy-peer-deps — этот режим требует точного match между package.json и package-lock.json. Mismatch → npm error Missing: <pkg>@<version> from lock file → builder fails → docker compose --abort-on-container-exit → весь deploy aborts (frontend + backend rollback).

• Pre-push check: git diff main..HEAD -- frontend/package.json frontend/package-lock.json — если только один из двух тронут → STOP, regen lock.
• Imports без deps entry (TypeScript авто-resolve через transitive) — latent bomb до first npm ci.
• Reference incident: PR #344 (2026-05-17) добавил lucide-react без regen lockfile → deploy #135 fail → P0 hotfix PR #345 (commit 6ee20294f2).

Prettier / lint

• 2 spaces, trailing comma, double quotes (config)
• prettier hook auto-rewrites файл → нужен повторный git add
• ESLint в pre-commit: no unused imports, no console.log, exhaustive deps

Запреты

• ❌ any в TypeScript — unknown + type guard
• ❌ useEffect для HTTP — TanStack Query
• ❌ pages/ router — только app/
• ❌ console.log в prod-коде
• ❌ Inline в href/src без validation (XSS vector)
• ❌ Hardcoded URLs — process.env.NEXT_PUBLIC_API_URL