React

React & TypeScript Frontend Guide

Use this skill when modifying, extending, or refactoring the frontend codebase in web/.

---

1. Technical Stack

• Core: React 19 (compatible with React Compiler) & TypeScript 6.
• Routing: TanStack Router (Vite file-based routing plugin).
• State & Query: TanStack Query (React Query) for API interactions.
• Forms: TanStack Form + Zod validation.
• Styling: Tailwind CSS v4 (configured via @tailwindcss/vite).
• Notifications: Sonner (toast).
• Icons: Lucide React.

---

2. React 19 & TypeScript Best Practices

• Strict Typing: Always define TypeScript types/interfaces for component props, API request/response structures, and state.
• Functional Components: Write pure functional components.
• React Compiler: React Compiler is enabled. Avoid manual optimizations using useMemo or useCallback for simple variables or handlers unless explicitly required for stability of dependency arrays in deep custom hooks. Let the compiler optimize renders automatically.
• File Structure:
  • src/components/: Shared UI components (like common/Button.tsx, common/Input.tsx).
  • src/features/: Complex feature-specific components (e.g., todo/TodoList.tsx).
  • src/hooks/: Reusable hooks.
  • src/routes/: Route definitions matching TanStack Router conventions.

---

3. TanStack Router & Routing

• Route Definitions: Located under src/routes/. Defined via createFileRoute.

• Navigation:

  • Use <Link to="..."> for declarative navigation to support type-safe routes.

  • Use useNavigate for programmatic navigation:

    const navigate = useNavigate();
    navigate({ to: "/todos" });
    

• Route Trees: The route tree is automatically generated under src/routeTree.gen.ts. Never edit this file manually.

---

4. Data Fetching & Mutations (TanStack Query)

• Isolation: Keep query and mutation hooks separate from component logic.

  • Queries belong in src/hooks/queries/.
  • Mutations belong in src/hooks/mutations/.

• Invalidation: Always invalidate the query cache on mutation success to keep the UI in sync:

  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: async (data) => {
      await client.post("/v2/todos/", data);
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["todos"] });
    },
  });
  

---

5. Forms & Schema Validation (TanStack Form + Zod)

• Setup: Use useForm from @tanstack/react-form combined with a Zod schema from src/models/.

• Form Submission:

  const form = useForm({
    defaultValues: { title: "", description: "" },
    onSubmit: async ({ value }) => {
      await createTodo(value);
    },
  });
  

• Inputs & Fields: Bind fields using form.Field and display validation errors safely:

  <form.Field
    name="title"
    validators={{
      onChange: todoSchema.shape.title,
    }}
    children={(field) => (
      <Input
        value={field.state.value}
        onChange={(e) => field.handleChange(e.target.value)}
        error={field.state.meta.errors.join(", ")}
      />
    )}
  />
  

---

6. Styling & UI Design

• Tailwind CSS v4: Use standard utility classes. Customize styling themes through the global CSS variables.
• Animations: Apply micro-interactions and transitions (e.g. transition-all, animate-fade-in-up, hover:shadow-lg) to improve visual feedback.
• Toasts: Handle operational successes and failures uniformly using Sonner's toast.success and toast.error.