frontend

React & Frontend Coding Guidelines

General Guidelines

• Use the pnpm package manager
• When interacting with the server, prefer the @gram/sdk package (sourced from workspace at ./client/sdk)
• The document client/sdk/REACT_QUERY.md is very helpful for understanding how to use React Query hooks that come with the SDK.
• For data fetching and server state, use @tanstack/react-query instead of manual useEffect/useState patterns
• When invalidating React Query caches after mutations, invalidate ALL relevant query keys — not just the most specific one. Different hooks may use different query key prefixes for the same data (e.g., queryKeyInstance vs toolsets.getBySlug). Use broad invalidation helpers like invalidateAllToolset(queryClient) to ensure all consumers refresh.

Component Structure and Reuse

The core rule: every UI pattern that appears in more than two places must be centralized so it can be changed in a single location.

Check components/ before writing anything

Before writing any JSX for a UI element, check client/dashboard/src/components/ for an existing component. This includes layout wrappers, table headers, empty states, filter pill groups, search inputs, badges, cards — anything. Reuse what exists. Never create a one-off <div className="..."> when a named component already exists for that purpose.

If no component exists and you expect the pattern to appear in more than a few places across the app, create one in client/dashboard/src/components/ before using it. Name it for what it is, not where it happens to appear first (e.g., PageTabsTrigger, not SourceDetailTabTrigger).