Cursor rule

1---
2description: React webapp conventions (Math Tutoring App)
3globs: webapp/**/*.{tsx,ts}
4alwaysApply: false
5---
6 
7# React Patterns — `webapp/`
8 
9Stack: **React 19**, **Vite**, **React Router**, **Firebase** (client SDK).
10 
11## useEffect rules (read first)
12 
13- **Computed values → plain vars, not state.** Never use `useEffect` to sync props into state. Derive inline.
14- **Router-driven resets → `key`, not `useEffect`.** When a screen must reinitialize from a route param (or equivalent identity), let the parent set `key={…}` to remount instead of mirroring props into state in an effect.
15- **Callbacks in deps → `useEffectEvent`.** Never put a parent-supplied callback directly in a `useEffect` dependency array — it may not be stable. Wrap it with `useEffectEvent`. Prefer `useEffectEvent` over `useCallback` for this.
16- **“Latest value” reads → `useEffectEvent`.** If you need a value inside an effect but don’t want it to re-trigger the effect, read it inside a `useEffectEvent` wrapper.
17- **Fetching / async load → custom hooks only.** Never perform data loading (Firestore queries, `fetch` to the Express API, etc.) directly inside `useEffect` in a route or feature component. Use a `useXxx` hook in `src/hooks/` that encapsulates loading (e.g. TanStack Query, or a dedicated hook that wraps your service calls). Components call hooks; they don’t inline async load effects.
18- **Expensive calculations → `useMemo`.** Don’t compute inside an effect and write to state unless it’s truly an external sync; derive or memoize.
19 
20**Exceptions:** Long-lived **subscriptions** (e.g. Firebase `onAuthStateChanged` in `AuthProvider`) belong in an effect with a proper cleanup return — that is not “fetching”; keep listeners from leaking.
21 
22```tsx
23// Rules 4 & 3 — useEffectEvent for latest values and unstable callbacks
24import { useEffect, useEffectEvent, useState } from 'react';
25 
26function TypingIndicator({ conversationId, onTick }: Props) {
27  const [dots, setDots] = useState(1);
28 
29  const fireTick = useEffectEvent(() => {
30    setDots((d) => (d % 3) + 1);
31    onTick(); // parent callback — not listed in useEffect deps
32  });
33 
34  useEffect(() => {
35    const id = setInterval(fireTick, 500);
36    return () => clearInterval(id);
37  }, [conversationId]); // only remount interval when conversation changes
38}
39 
40// Rules 2 & 1 — key for remount; derived strings, not effect-synced state
41// Parent (e.g. route wrapper)
42<Chat key={conversationId ?? 'new'} />
43 
44// Inside Chat — no useEffect to copy props into state
45function Chat({ conversationId }: { conversationId: string | null }) {
46  const { data } = useConversationHistory(); // Rule 5 — load via hook
47  const title = conversationId ? `Thread ${conversationId.slice(0, 8)}` : 'New chat'; // Rule 1
48  const sortedMessages = useMemo(
49    () => [...(data?.messages ?? [])].sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime()),
50    [data?.messages]
51  ); // Rule 6
52}
53```
54 
55## Custom hooks per resource
56 
57- Each **distinct data domain** gets its own hook in `src/hooks/`, named after that domain (`useAuth`, `useConversationHistory`, etc.).
58- **One hook per resource shape** where it helps clarity: e.g. conversation list/history vs. auth session vs. a single upload flow — don’t stuff unrelated async into one mega-hook.
59- **Services stay in `src/services/`** (`chatService`, `api`, `storageService`); hooks orchestrate those (and caching libraries if you add them). Screen components should not import `chatService` / call `fetch` directly for load paths that belong in a hook.
60 
61```ts
62// ✅ GOOD — names reflect resources / concerns
63useAuth();
64useConversationHistory();
65 
66// ❌ BAD — Chat.tsx importing loadConversationHistory and wiring useEffect inline for the main load path
67```
68 
69## Layout
70 
71| Area | Path |
72|------|------|
73| App shell & routes | `webapp/src/App.tsx`, `webapp/src/main.tsx` |
74| Screens / features | `webapp/src/components/` (e.g. `Chat.tsx`, `Login.tsx`, `SignUp.tsx`) |
75| Design system | `webapp/src/components/design-system/` |
76| Hooks | `webapp/src/hooks/` |
77| Context | `webapp/src/contexts/` |
78| Client API / streaming | `webapp/src/services/api.ts` |
79| Firestore / persistence | `webapp/src/services/chatService.ts`, `storageService.ts` |
80| Global styles / tokens | `webapp/src/styles/tokens.ts` |
81 
82There is no `src/pages/` tree; route-level views live under `src/components/`.
83 
84## Data & side effects
85 
86- **Firestore reads/writes** run in the **webapp** via the Firebase client SDK — not from the Express API for normal chat persistence.
87- **LLM / OpenAI** runs only **server-side** (`api/`). The webapp uses Express for chat streaming (`api.ts` / SSE) and sends **Firebase ID tokens**; never embed provider API keys in the client.
88- Prefer **custom hooks** (`useAuth`, resource hooks above) for shared data and UI coordination.
89 
90## Components
91 
92- Prefer **focused components** under `src/components/` over single huge files; shared primitives live in `design-system/`.
93- Keep **accessibility** in mind for interactive controls (buttons, forms, chat input).
94