Frontend

Frontend

Owner: Frontend Engineering Last reviewed: 2026-Q2

The frontend is a Vite + React 19 + TypeScript app with Tailwind and Radix UI primitives. Authentication uses Clerk. API clients are generated from OpenAPI using Orval.

Key Paths

  • frontend/package.json – scripts (dev, build, preview, orval).
  • frontend/openapi.json – OpenAPI source for client generation.
  • frontend/orval.config.ts – Orval configuration → outputs to src/api/generated.
  • src/lib/* – API config and utilities.
  • src/api/* – Thin wrappers over generated clients.
  • src/components/* – UI primitives and feature components (kanban, layout, dialogs).
  • src/hooks/* – custom hooks (useApiError, useTasks, use-mobile).

Patterns

  • Data fetching: Use TanStack Query. Co-locate queries with features; keep caching and invalidations explicit.
  • Generated clients: Regenerate with npm run orval when backend changes OpenAPI. Do not hand-edit src/api/generated/*.
  • Generated code policy lives in generated-code.md.
  • Forms and validation: react-hook-form + zod schemas.
  • Styling: Tailwind v4 + utility helpers (clsx, tailwind-merge). Keep components accessible (Radix).
  • Frontend UX and state standards live in frontend-ux-standards.md.
  • Auth: Use @clerk/clerk-react. Read the publishable key from VITE_CLERK_PUBLISHABLE_KEY.
  • Routing: react-router-dom with route components in src/pages/* and layout in components/layout/*.

Error Handling

  • Centralize API error parsing in useApiError and handle toasts in UI.
  • Prefer user-friendly messages; log technical details to console only in dev.

Kanban Example

  • Drag & drop via @dnd-kit/*.
  • Data entities mirror backend schemas (items, columns, comments, profiles) via generated models (e.g., src/api/generated/models/*).
  • Mutations: keep optimistic updates safe; reconcile with server responses.

Performance

  • Code-split by route if payload grows; lazy-load heavy components.
  • Memoize expensive subtrees; avoid prop drilling by composing hooks.
  • Batch network calls where possible; leverage server pagination.

Testing & Linting

  • ESLint config in eslint.config.js. Keep type-aware rules enabled for production code.
  • Prefer component tests for complex UI and integration tests around critical flows.

Local Dev

  • Env: copy frontend/env.example to .env and set VITE_APP_API_URL to backend and Clerk publishable key.
  • Run: npm ci && npm run dev.
BackendAPI Style Guide