Cursor rule

1---
2globs:
3  - "packages/hermes-app/src/routes/**/*.tsx"
4---
5 
6# Hermes App - TanStack Router Rules
7 
8## Route File Structure
9 
10### File-Based Routing
11- Route files in `src/routes/`
12- File names determine route paths using dot notation
13- Special file names: `__root.tsx`, `index.tsx`
14 
15```
16routes/
17├── __root.tsx           # Root layout (wraps all routes)
18├── index.tsx            # Home page (/)
19├── queue.tsx            # /queue
20├── settings.tsx         # /settings
21├── auth.login.tsx       # /auth/login
22└── auth.signup.tsx      # /auth/signup
23```
24 
25### Route File Template
26```typescript
27import { createFileRoute } from "@tanstack/react-router";
28 
29export const Route = createFileRoute("/route-path")({
30  component: RouteComponent,
31  loader: async ({ context, params }) => {
32    // Load data
33    return { data };
34  },
35  errorComponent: ErrorComponent,
36  pendingComponent: LoadingComponent,
37  beforeLoad: async ({ context, location }) => {
38    // Auth checks, redirects
39  },
40});
41 
42function RouteComponent() {
43  const data = Route.useLoaderData();
44  return <div>{/* Route content */}</div>;
45}
46```
47 
48## Root Layout (__root.tsx)
49 
50```typescript
51import { createRootRoute, Outlet } from "@tanstack/react-router";
52import { AppLayout } from "@/components/layout/AppLayout";
53 
54export const Route = createRootRoute({
55  component: RootLayout,
56  errorComponent: RootErrorComponent,
57});
58 
59function RootLayout() {
60  return (
61    <AppLayout>
62      <Outlet />
63    </AppLayout>
64  );
65}
66```
67 
68## Data Loading
69 
70### Loaders
71```typescript
72export const Route = createFileRoute("/downloads")({
73  loader: async ({ context }) => {
74    const downloads = await fetchDownloads();
75    const stats = await fetchStats();
76    return { downloads, stats };
77  },
78  component: DownloadsPage,
79});
80 
81function DownloadsPage() {
82  const { downloads, stats } = Route.useLoaderData();
83  return (
84    <div>
85      <Stats data={stats} />
86      <DownloadList items={downloads} />
87    </div>
88  );
89}
90```
91 
92### With Search Params
93```typescript
94export const Route = createFileRoute("/downloads")({
95  validateSearch: (search: Record<string, unknown>) => {
96    return {
97      status: (search.status as string) || "all",
98      page: Number(search.page) || 1,
99    };
100  },
101  loader: async ({ context, search }) => {
102    const downloads = await fetchDownloads({
103      status: search.status,
104      page: search.page,
105    });
106    return { downloads };
107  },
108});
109```
110 
111## Navigation
112 
113### Link Component
114```typescript
115import { Link } from "@tanstack/react-router";
116 
117<Link to="/queue" className="nav-link" activeProps={{ className: "active" }}>
118  Queue
119</Link>
120 
121// With params
122<Link to="/downloads/$downloadId" params={{ downloadId: "123" }}>
123  View Download
124</Link>
125 
126// With search
127<Link to="/downloads" search={{ status: "completed", page: 1 }}>
128  Completed
129</Link>
130```
131 
132### Programmatic Navigation
133```typescript
134import { useNavigate } from "@tanstack/react-router";
135 
136function MyComponent() {
137  const navigate = useNavigate();
138 
139  const handleClick = () => {
140    navigate({ to: "/downloads", search: { status: "active" } });
141  };
142 
143  return <button onClick={handleClick}>Go</button>;
144}
145```
146 
147## Protected Routes
148 
149```typescript
150import { createFileRoute, redirect } from "@tanstack/react-router";
151import { isAuthenticated } from "@/services/auth";
152 
153export const Route = createFileRoute("/protected")({
154  beforeLoad: async ({ context, location }) => {
155    if (!isAuthenticated()) {
156      throw redirect({
157        to: "/auth/login",
158        search: { redirect: location.href },
159      });
160    }
161  },
162  component: ProtectedPage,
163});
164```
165 
166## Search Params
167 
168### Validating Search
169```typescript
170import { z } from "zod";
171 
172const searchSchema = z.object({
173  status: z.enum(["all", "active", "completed", "failed"]).default("all"),
174  sort: z.enum(["date", "title", "size"]).default("date"),
175  page: z.number().int().positive().default(1),
176  limit: z.number().int().positive().max(100).default(20),
177});
178 
179export const Route = createFileRoute("/downloads")({
180  validateSearch: (search) => searchSchema.parse(search),
181});
182 
183function Component() {
184  const search = Route.useSearch();
185  // search is fully typed
186}
187```
188 
189### Updating Search
190```typescript
191const navigate = useNavigate();
192const search = Route.useSearch();
193 
194const updateStatus = (status: string) => {
195  navigate({
196    search: (prev) => ({
197      ...prev,
198      status,
199      page: 1, // Reset page
200    }),
201  });
202};
203```
204 
205## Route Params
206 
207```typescript
208// File: routes/downloads.$downloadId.tsx
209export const Route = createFileRoute("/downloads/$downloadId")({
210  loader: async ({ params }) => {
211    const download = await fetchDownload(params.downloadId);
212    return { download };
213  },
214  component: DownloadDetail,
215});
216 
217function DownloadDetail() {
218  const { download } = Route.useLoaderData();
219  const { downloadId } = Route.useParams();
220  return <div>{download.title}</div>;
221}
222```
223 
224## Error Handling
225 
226```typescript
227export const Route = createFileRoute("/route")({
228  errorComponent: RouteErrorComponent,
229});
230 
231function RouteErrorComponent({ error }: { error: Error }) {
232  return (
233    <div className="error-container">
234      <h1>Something went wrong</h1>
235      <p>{error.message}</p>
236    </div>
237  );
238}
239```
240 
241### Loader Errors
242```typescript
243export const Route = createFileRoute("/data")({
244  loader: async () => {
245    const data = await fetchData();
246    if (!data) throw new Error("Data not found");
247    return { data };
248  },
249});
250```
251 
252## Loading States
253 
254```typescript
255export const Route = createFileRoute("/downloads")({
256  loader: fetchDownloads,
257  pendingComponent: LoadingDownloads,
258  component: DownloadsPage,
259});
260 
261function LoadingDownloads() {
262  return <div>Loading...</div>;
263}
264```
265 
266## Route Context
267 
268### Providing Context
269```typescript
270// In root route
271export const Route = createRootRoute({
272  beforeLoad: async () => {
273    const user = await getCurrentUser();
274    const config = await getConfig();
275    return { auth: { user }, config };
276  },
277});
278```
279 
280### Consuming Context
281```typescript
282export const Route = createFileRoute("/profile")({
283  beforeLoad: ({ context }) => {
284    const user = context.auth?.user;
285    return { user };
286  },
287});
288```
289 
290## Code Splitting
291 
292```typescript
293import { createFileRoute, lazyRouteComponent } from "@tanstack/react-router";
294 
295export const Route = createFileRoute("/large")({
296  component: lazyRouteComponent(() => import("./LargeComponent")),
297});
298```
299 
300