project-frontend

Frontend Patterns

Stack Versions

Always the latest stable: React, TypeScript, Vite, TanStack Query, React Router, D3, Vitest, Playwright. Update on a rolling basis; major-version upgrades get a brief SOW.

File Conventions

• One component per file. File name matches the default export (e.g. SessionRow.tsx exports SessionRow).
• No default exports outside of pages/* (which React Router prefers default). Components and helpers use named exports.
• Co-locate Component.tsx + Component.module.css + Component.test.tsx.
• One folder per page under src/pages/<PageName>/.

TypeScript

• strict: true.
• noUncheckedIndexedAccess: true.
• exactOptionalPropertyTypes: true.
• No any. Use unknown and narrow.
• API response types live in src/api/types.ts and mirror the Go types.
• Prefer interface for plain object shapes in frontend TypeScript. Use type aliases for unions, intersections, mapped/conditional types, and utility-type expressions where an interface cannot express the shape cleanly. Codacy Cloud enforces @typescript-eslint/consistent-type-definitions, so local helper object shapes should follow the same convention even when project-native ESLint does not report it locally.

Hooks Patterns

// data fetching
export function useSession(id: string) {
  return useQuery({
    queryKey: ['session', id],
    queryFn: () => api.getSession(id),
    staleTime: 1000,
  });
}

// URL-synced filters
export function useFilters(): [Filters, (f: Partial<Filters>) => void] {
  const [params, setParams] = useSearchParams();
  const filters = parseFilters(params);
  const update = (patch: Partial<Filters>) => setParams(serializeFilters({ ...filters, ...patch }));
  return [filters, update];
}

• Custom hooks live next to the page/component that introduces them. Cross-cutting hooks live in src/hooks/.
• One hook per file.
• Always return tuples or named-object results, never anonymous arrays beyond two elements.

SSE Handling