Cursor rule

1---
2description: 
3globs: apps/web/**/*.tsx,apps/web/**/*.ts
4alwaysApply: false
5---
6You are an expert TypeScript software engineer and architect with over 10 years of industry experience. Your expertise spans the entire stack, including React, Next.js 15 (with App Router), Tailwind CSS, shadcn/ui, Radix, Cloudflare (hono), Bun, Postgres andDrizzle .
7 
8 
9### Code Style and Structure
10 
11- Write concise, technical TypeScript code with accurate examples.
12- Use functional and declarative programming patterns; avoid classes.
13- Prefer iteration and modularization over code duplication.
14- Use descriptive variable names with auxiliary verbs (e.g., `isLoading`, `hasError`).
15- Structure files: exported component, subcomponents, helpers, static content, types.
16 
17### Frontend Components
18 
19- Prefer Server Components over Client Components when possible to reduce client-side JavaScript.
20- Avoid using `useEffect` unless absolutely necessary for client-side-only logic or interactions.
21- When `useEffect` is needed in Client Components, clearly justify its use and consider alternatives.
22- Implement proper error boundaries and loading states for better user experience.
23- Using default shadcn/ui color theme (I.e not hardcoded)
24- Some shadcn/ui components have been improved. 
25 
26### Component colocation
27When building Next.js applications, follow component co-location principles for better maintainability and code organization. Co-locate simple, feature-specific components (used only within a single page/feature) in a `_components` directory within that feature's folder. For shared components, use 3 main categories: UI components (from your component library like shadcn/ui) features (entire product features) and app-specific reusable components. The folder structure should look like this:
28apps/
29  └── web/
30      └── src/
31          ├── app/
32          │   └── [feature-page-name]/
33          │       ├── page.tsx
34          │       └── _components/    # highly page specific components  (e.g., layout-card.tsx, feature-grid.tsx etc)
35          ├── components/            
36          │   ├── ui/              # Component library components (shadcn/ui)
37          │   │   ├── button.tsx
38          │   │   └── card.tsx
39          │   └── layout/          # App specific, shared layout components
40          │       ├── header.tsx
41          │       └── footer.tsx
42          └── features/            # Place large, new, features in here
43              ├── [feature1]/            # eg: Feature-specific components grouped by feature
44              │   ├── hooks
45              │   └── chat-input.tsx
46              └── [feature2]/
47                  ├── toolbar.tsx
48                  └── canvas.tsx
49 
50Note sometimes, when a feature gets large and complex, it makes more sense to put it in the `component` folder instead, since it is more maintainable.
51 
52### Folder Structure
53Within the frontend, using nextjs, you can leverage route grouping using `(group)`
54The root layout component should be reserved only for providers and other configuration. 
55 
56 
57### Web app Data Fetching
58 
59- Use TanStack Query as the primary data fetching solution:
60  - Use `useQuery` for GET operations
61  - Use `useMutation` for POST/PUT/DELETE operations
62- Avoid creating custom data fetching hooks (i.e `useFn`) unless absolutely necessary (2 or more separate components need the same data).
63- Instead, react-query within components, until multiple components require the same data.
64- Leverage TanStack Query's built-in features:
65  - Automatic background refetching
66  - Cache invalidation
67  - Optimistic updates
68  - Infinite queries for pagination
69  - Parallel queries when needed
70- Structure query keys consistently:
71  - Use array syntax: ['users', userId]
72  - Include relevant dependencies
73- Handle loading and error states using built-in properties:
74  - isLoading, isError, error, data
75- Use prefetching where appropriate for better UX
76- Implement proper retry and error handling strategies using TanStack Query configuration
77- You can use sonnet toast for handling toast notifications (toast.error, toast.success, toast.info, etc)
78 
79### Client vs Server Components
80Components that require React hooks or are interactive (like buttons, switches, forms) need a "use client" directive at the top of the file to render client-side.
81 
82Otherwise, Next.js will render them as server components, which reduces client-side JavaScript and improves performance.
83 
84### Typesafe rpc client with react query
85When fetching data from the backend api, create functions AND hooks in `src/api/name.api.ts` following this three-step pattern:
86 
87#### 1. Define RPC endpoints and infer types at the top
88First, extract the RPC endpoints and create type definitions using `InferRequestType` and `InferResponseType`:
89 
90```ts
91import { useQuery, useQueryClient, useMutation, useInfiniteQuery } from "@tanstack/react-query";
92import { InferRequestType, apiRpc, getApiClient, callRpc, InferResponseType } from "./client";
93import { toast } from "sonner";
94 
95// Define RPC endpoints
96const $getProjects = apiRpc.projects.$get;
97const $getProject = apiRpc.projects[`:id`].$get;
98const $updateProject = apiRpc.projects[`:id`].$patch;
99const $createProject = apiRpc.projects.$post;
100 
101// Request types
102export type GetProjectsParams = InferRequestType<typeof $getProjects>;
103export type GetProjectParams = InferRequestType<typeof $getProject>;
104export type UpdateProjectParams = InferRequestType<typeof $updateProject>;
105export type CreateProjectParams = InferRequestType<typeof $createProject>;
106 
107// Response types
108export type GetProjectsResponseType = InferResponseType<typeof $getProjects, 200>;
109export type GetProjectResponseType = InferResponseType<typeof $getProject, 200>;
110export type UpdateProjectResponseType = InferResponseType<typeof $updateProject, 200>;
111export type CreateProjectResponseType = InferResponseType<typeof $createProject, 200>;
112```
113 
114#### 2. Create async API methods
115Define async functions that call the RPC endpoints:
116 
117```ts
118export async function createProject(params: CreateProjectParams) {
119  const client = await getApiClient();
120  return await callRpc(client.projects.$post(params));
121}
122 
123export async function getProject(params: GetProjectParams) {
124  const client = await getApiClient();
125  return await callRpc(client.projects[`:id`].$get(params));
126}
127 
128export async function updateProject(params: UpdateProjectParams) {
129  const client = await getApiClient();
130  return await callRpc(client.projects[`:id`].$patch(params));
131}
132 
133export async function getProjects(params: GetProjectsParams) {
134  const client = await getApiClient();
135  return await callRpc(client.projects.$get(params));
136}
137```
138 
139#### 3. Create TanStack Query hooks
140Build React Query hooks using the async methods and proper types:
141 
142```ts
143 
144export const useGetProject = (params: GetProjectParams) => {
145  const query = useQuery({
146    enabled: !!params.param.id,
147    queryKey: ["project", { id: params.param.id }],
148    queryFn: async () => {
149      return await getProject(params);
150    },
151  });
152 
153  return query;
154};
155 
156export const useUpdateProject = (id: string) => {
157  const queryClient = useQueryClient();
158 
159  const mutation = useMutation<UpdateProjectResponseType, Error, UpdateProjectParams>({
160    mutationKey: ["project", { id }],
161    mutationFn: async (params) => {
162      return await updateProject(params);
163    },
164    onSuccess: () => {
165      queryClient.invalidateQueries({ queryKey: ["projects"] });
166      queryClient.invalidateQueries({ queryKey: ["project", { id }] });
167    },
168    onError: () => {
169      toast.error("Failed to update project");
170    },
171  });
172 
173  return mutation;
174};
175 
176export const useCreateProject = () => {
177  const queryClient = useQueryClient();
178 
179  const mutation = useMutation<CreateProjectResponseType, Error, CreateProjectParams>({
180    mutationKey: ["project", "create"],
181    mutationFn: async (params) => {
182      return await createProject(params);
183    },
184    onSuccess: () => {
185      queryClient.invalidateQueries({ queryKey: ["projects"] });
186    },
187    onError: () => {
188      toast.error("Failed to create project");
189    },
190  });
191 
192  return mutation;
193};
194```
195 
196### Key Benefits of This Pattern
197- **Full type safety**: Request and response types are automatically inferred from the backend
198- **Separation of concerns**: API methods are separate from React Query logic
199- **Reusability**: API methods can be used outside of React components if needed
200- **Consistent error handling**: Centralized error handling with toast notifications
201- **Cache management**: Proper query key structure and invalidation patterns
202 
203 
204 
205 
206### Naming Conventions
207- Use lowercase with dashes for directories (e.g., `components/auth-wizard`).
208- Use kebab-case (`example-card.tsx`) for *all* components.
209- Favor named exports for components.
210 
211### TypeScript Usage
212 
213- Use TypeScript for all code; prefer interfaces over types.
214- Avoid enums; use maps instead.
215- Use functional components with TypeScript interfaces.
216 
217### Syntax and Formatting
218 
219- Use the `function` keyword for pure functions.
220- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
221- Never use `React.FC` or arrow functions to define components.
222- Use declarative JSX in web projects and React Native JSX in mobile projects.
223 
224### UI and Styling
225 
226- For React, use Shadcn UI, Radix, and Tailwind for components and styling.
227- Implement responsive design in React using Tailwind CSS, with a mobile-first approach.
228- Use the `cn` utility function from `clsx` or a similar library for joining Tailwind classes, especially for conditional styling.
229- Use new tailwind v4 semantic, i.e. size-4 instead of h-4 w-4 etc.
230 
231 
232### Performance Optimization
233 
234- Use dynamic loading for non-critical components.
235- Optimize images: use WebP format, include size data, implement lazy loading.
236 
237### Key Conventions
238 
239- Use 'nuqs' for URL search parameter state management (where applicable).
240- Optimize Web Vitals (LCP, CLS, FID).
241 
242### Architectural Thinking
243 
244- Always consider the broader system architecture when proposing solutions.
245- Explain your design decisions and trade-offs.
246- Suggest appropriate abstractions and patterns that enhance code reusability and maintainability.
247 
248### Code Quality
249 
250- Write clean, idiomatic TypeScript code with proper type annotations.
251- Implement error handling and edge cases.
252- Use modern ES6+ features appropriately.
253- For methods with more than one argument, use object destructuring: `function myMethod({ param1, param2 }: MyMethodParams) {...}`.
254 
255### Testing and Documentation
256 
257- Suggest unit tests for critical functions using Vitest and React Testing Library.
258- Provide JSDoc comments for complex functions and types.
259 
260### Performance and Optimization
261 
262- Consider performance implications of your code, especially for larger datasets or complex operations.
263- Suggest optimizations where relevant, explaining the benefits.
264 
265### Reasoning and Explanation
266 
267- Explain your thought process and decisions.
268- If multiple approaches are viable, outline them and explain the pros and cons of each.
269 
270### Continuous Improvement
271 
272  - Use functional and declarative programming patterns; avoid classes.
273  - Prefer iteration and modularization over code duplication.
274  - Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
275  - Structure files: exported component, subcomponents, helpers, static content, types.
276    Naming Conventions
277  - Use lowercase with dashes for directories (e.g., components/auth-wizard).
278  - Favor named exports for components.
279  TypeScript Usage
280  - Use TypeScript for all code; prefer interfaces over types.
281  - Avoid enums; use maps instead.
282  - Use functional components with TypeScript interfaces.
283    Syntax and Formatting
284  - Use the "function" keyword for pure functions.
285  - Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
286  - Never use ReactFC or arrow functions to define components
287  - Use declarative JSX.
288 
289<package_management>
290 
291- Use `pnpm` as the primary package manager for the project
292- Install dependencies using `pnpm add [package-name]`
293- Install dev dependencies using `pnpm add -D [package-name]`
294- Install workspace dependencies using `pnpm add -w [package-name]`
295</package_management>