Cursor rule

1---
2description: Useful for building react full stack applications
3globs: web/*.{ts,tsx,js,jsx}
4alwaysApply: true
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 two main categories: UI components (from your component library like shadcn/ui) and app-specific reusable components. The folder structure should look like this:
28apps/
29  └── web/
30      └── src/
31          ├── app/
32          │   └── [feature]/
33          │       ├── page.tsx
34          │       └── _components/    # highly specific feature components (e.g., dashboard-stats.tsx)
35          └── components/            
36              ├── ui/                # Component library components (shadcn/ui)
37              │   ├── button.tsx
38              │   └── card.tsx
39              └── layout/       # App specific, shared components, or if the feature is very large/complex put, create its own folder     
40                  ├── header.tsx
41                  └── footer.tsx
42              └── forms/            
43 
44Note 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.
45 
46### Folder Structure
47Within the frontend, using nextjs, you can leverage route grouping using `(group)`
48The root layout component should be reserved only for providers and other configuration. 
49 
50 
51### Web app Data Fetching
52 
53- Use TanStack Query as the primary data fetching solution:
54  - Use `useQuery` for GET operations
55  - Use `useMutation` for POST/PUT/DELETE operations
56- Avoid creating custom data fetching hooks (i.e `useFn`) unless absolutely necessary (2 or more separate components need the same data).
57- Instead, react-query within components, until multiple components require the same data.
58- Leverage TanStack Query's built-in features:
59  - Automatic background refetching
60  - Cache invalidation
61  - Optimistic updates
62  - Infinite queries for pagination
63  - Parallel queries when needed
64- Structure query keys consistently:
65  - Use array syntax: ['users', userId]
66  - Include relevant dependencies
67- Handle loading and error states using built-in properties:
68  - isLoading, isError, error, data
69- Use prefetching where appropriate for better UX
70- Implement proper retry and error handling strategies using TanStack Query configuration
71- You can use sonnet toast for handling toast notifications (toast.error, toast.success, toast.info, etc)
72 
73### Client vs Server Components
74Components 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.
75 
76Otherwise, Next.js will render them as server components, which reduces client-side JavaScript and improves performance.
77 
78### Typesafe rpc client with react query
79When fetching data from the backend api, create functions in `src/api/name.api.ts`
80For example:
81```ts
82import { apiRpc, getApiClient, InferRequestType } from "./client";
83 
84const $createPost = apiRpc.posts.$post;
85// Simple get
86export async function getPosts() {
87  const client = await getApiClient();
88 
89  const response = await client.posts.$get();
90  return response.json();
91}
92// Safely leverage the typed params elsewhere within the nextjs application 
93export type CreatePostParams = InferRequestType<typeof $createPost>["json"];
94export async function createPost(params: CreatePostParams) {
95  const client = await getApiClient();
96 
97  const response = await client.posts.$post({ json: params });
98  // This returns fully typed response, we do not need to create a response interface
99  return response.json();
100}
101```
102 
103### Response types
104Creating response types when using the rpc client is not required. The hono-rpc we use lets us infer the response types safely.
105 
106 
107 
108 
109### Naming Conventions
110- Use lowercase with dashes for directories (e.g., `components/auth-wizard`).
111- Use kebab-case (`example-card.tsx`) for *all* components.
112- Favor named exports for components.
113 
114### TypeScript Usage
115 
116- Use TypeScript for all code; prefer interfaces over types.
117- Avoid enums; use maps instead.
118- Use functional components with TypeScript interfaces.
119 
120### Syntax and Formatting
121 
122- Use the `function` keyword for pure functions.
123- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
124- Never use `React.FC` or arrow functions to define components.
125- Use declarative JSX in web projects and React Native JSX in mobile projects.
126 
127### UI and Styling
128 
129- For React, use Shadcn UI, Radix, and Tailwind for components and styling.
130- Implement responsive design in React using Tailwind CSS, with a mobile-first approach.
131- Use the `cn` utility function from `clsx` or a similar library for joining Tailwind classes, especially for conditional styling.
132- Use new tailwind v4 semantic, i.e. size-4 instead of h-4 w-4 etc.
133 
134 
135### Performance Optimization
136 
137- Use dynamic loading for non-critical components.
138- Optimize images: use WebP format, include size data, implement lazy loading.
139 
140### Key Conventions
141 
142- Use 'nuqs' for URL search parameter state management (where applicable).
143- Optimize Web Vitals (LCP, CLS, FID).
144 
145### Architectural Thinking
146 
147- Always consider the broader system architecture when proposing solutions.
148- Explain your design decisions and trade-offs.
149- Suggest appropriate abstractions and patterns that enhance code reusability and maintainability.
150 
151### Code Quality
152 
153- Write clean, idiomatic TypeScript code with proper type annotations.
154- Implement error handling and edge cases.
155- Use modern ES6+ features appropriately.
156- For methods with more than one argument, use object destructuring: `function myMethod({ param1, param2 }: MyMethodParams) {...}`.
157 
158### Testing and Documentation
159 
160- Suggest unit tests for critical functions using Vitest and React Testing Library.
161- Provide JSDoc comments for complex functions and types.
162 
163### Performance and Optimization
164 
165- Consider performance implications of your code, especially for larger datasets or complex operations.
166- Suggest optimizations where relevant, explaining the benefits.
167 
168### Reasoning and Explanation
169 
170- Explain your thought process and decisions.
171- If multiple approaches are viable, outline them and explain the pros and cons of each.
172 
173### Continuous Improvement
174 
175  - Use functional and declarative programming patterns; avoid classes.
176  - Prefer iteration and modularization over code duplication.
177  - Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
178  - Structure files: exported component, subcomponents, helpers, static content, types.
179    Naming Conventions
180  - Use lowercase with dashes for directories (e.g., components/auth-wizard).
181  - Favor named exports for components.
182  TypeScript Usage
183  - Use TypeScript for all code; prefer interfaces over types.
184  - Avoid enums; use maps instead.
185  - Use functional components with TypeScript interfaces.
186    Syntax and Formatting
187  - Use the "function" keyword for pure functions.
188  - Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
189  - Never use ReactFC or arrow functions to define components
190  - Use declarative JSX.
191 
192<package_management>
193 
194- Use `pnpm` as the primary package manager for the project
195- Install dependencies using `pnpm add [package-name]`
196- Install dev dependencies using `pnpm add -D [package-name]`
197- Install workspace dependencies using `pnpm add -w [package-name]`
198</package_management>