Cursor rule

1---
2description: React Router
3globs: web/app/routes/**/*.tsx
4alwaysApply: false
5---
6## React Router
7 
8 
9- You are using the latest version of React Router (v7).
10- Always include the suffix `Page` when naming the default export of a route.
11- The primary export in a routes file should specify `loaderData` like `export default function RouteNamePage({ loaderData }: Route.ComponentProps)`. `loaderData` is the return value from `clientLoader`.
12- Use `href("/products/:id", { id: "abc123" })` to generate a url path for a route managed by the application.
13  - Look at [routes.ts](mdc:web/app/routes.ts) to determine what routes and path parameters exist.
14- Use `export async function clientLoader(loaderArgs: Route.ClientLoaderArgs)` to define a `clientLoader` on a route.
15- Do not define `Route.*` types, these are autogenerated and can be imported from `import type { Route } from "./+types/routeFileName"`
16- If URL parameters or query string values need to be checked before rendering the page, do this in a `clientLoader` and not in a `useEffect`
17- Never worry about generating types using `pnpm`
18- Use [`<AllMeta />`](web/app/components/shared/AllMeta.tsx) instead of MetaFunction or individual `<meta />` tags
19- Use the following pattern to reference query string values (i.e. `?theQueryStringParam=value`)
20 
21```typescript
22const [searchParams, _setSearchParams] = useSearchParams()
23// searchParams contains the value of all query string parameters
24const queryStringValue = searchParams.get("theQueryStringParam")
25```
26 
27### Loading Mock Data
28 
29Don't load mock data in the component function with `useEffect`. Instead, load data in a `clientLoader`:
30 
31```typescript
32// in mock.ts
33export async function getServerData(options: any) {
34  // ...
35}
36 
37// in web/app/routes/**/*.ts
38export async function clientLoader(loaderArgs: Route.ClientLoaderArgs) {
39  // no error reporting is needed, this will be handled by the `getServerData`
40  // mock loading functions should return result in a `data` key
41  const { data } = await getServerData({
42    /* ... */
43  });
44 
45  // the return result here is available in `loaderData`
46  return data;
47}
48```
49 
50### How to Use `clientLoader`
51 
52- `export async function clientLoader(loaderArgs: Route.ClientLoaderArgs) {`
53- Load any server data required for page load here, not in the component function.
54- Use `return redirect(href("/the/url"))` to redirect users
55- Use [getQueryParam](web/app/lib/utils.ts) to get query string variables
56- `throw new Response` if you need to mimic a 400, 500, etc error
57- `loaderArgs` and all sub-objects are all fully typed
58- `loaderArgs.params.id` to get URL parameters
59 
60### Loading Backend Data
61 
62- `~/configuration/client` re-exports all types and functions from `client/*`. Import from `~/configuration/client` instead of anything you find in the `client/` folder/package.
63- For each API endpoint, there's a fully typed async function that can be used to call it. Never attempt to call an API endpoint directly.
64  - Do not generate types for API parameters or responses. Reference the autogenerated types that are re-exported in `~/configuration/client`
65  - For instance, the `getSignedUrl` function in [web/client/sdk.gen.ts] has a `SignedUrlResponse` type in [web/client/types.gen.ts]
66  - This same type is used in the function signature, i.e. `type SignedUrlResponse = Awaited<ReturnType<typeof getSignedUrl>>["data"]`
67 
68- When using an import from `~/configuration/client`:
69  - use `body:` for request params
70  - always `const { data, error } = await theCall()`
71 
72`clientLoader` can only be used on initial page load within a route. If you need to load additional server data on component mount:
73 
74```tsx
75import { useQuery } from "@tanstack/react-query"
76import {
77  // these options correspond to the server route
78  createCheckoutSessionOptions,
79  publicClient,
80} from "~/configuration/client"
81 
82function TheComponent() {
83  const { data, error } = useQuery({
84    enabled: open,
85    ...createCheckoutSessionOptions({
86      // or `client` if authenticated
87      client: publicClient,
88      body: { /* API parameters here */ },
89    }),
90  })
91 
92  // remember to display errors by checking `error`
93}
94```
95