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 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, callRpc } from "./client";
83 
84const $createPost = apiRpc.posts.$post;
85// Simple get
86export async function getPosts() {
87  const client = await getApiClient();
88 
89  return callRpc(client.posts.$get());
90}
91// Safely leverage the typed params elsewhere within the nextjs application 
92export type CreatePostParams = InferRequestType<typeof $createPost>["json"];
93export async function createPost(params: CreatePostParams) {
94  const client = await getApiClient();
95  // This returns fully typed response, we do not need to create a response interface
96  return callRpc(client.posts.$post({ json: params }));
97}
98```
99 
100### Response types
101Creating response types when using the rpc client is not required. The hono-rpc we use lets us infer the response types safely.
102 
103 
104 
105 
106### Naming Conventions
107- Use lowercase with dashes for directories (e.g., `components/auth-wizard`).
108- Use kebab-case (`example-card.tsx`) for *all* components.
109- Favor named exports for components.
110 
111### TypeScript Usage
112 
113- Use TypeScript for all code; prefer interfaces over types.
114- Avoid enums; use maps instead.
115- Use functional components with TypeScript interfaces.
116 
117### Syntax and Formatting
118 
119- Use the `function` keyword for pure functions.
120- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
121- Never use `React.FC` or arrow functions to define components.
122- Use declarative JSX in web projects and React Native JSX in mobile projects.
123 
124### UI and Styling
125 
126- For React, use Shadcn UI, Radix, and Tailwind for components and styling.
127- Implement responsive design in React using Tailwind CSS, with a mobile-first approach.
128- Use the `cn` utility function from `clsx` or a similar library for joining Tailwind classes, especially for conditional styling.
129- Use new tailwind v4 semantic, i.e. size-4 instead of h-4 w-4 etc.
130 
131 
132### Performance Optimization
133 
134- Use dynamic loading for non-critical components.
135- Optimize images: use WebP format, include size data, implement lazy loading.
136 
137### Key Conventions
138 
139- Use 'nuqs' for URL search parameter state management (where applicable).
140- Optimize Web Vitals (LCP, CLS, FID).
141 
142### Architectural Thinking
143 
144- Always consider the broader system architecture when proposing solutions.
145- Explain your design decisions and trade-offs.
146- Suggest appropriate abstractions and patterns that enhance code reusability and maintainability.
147 
148### Code Quality
149 
150- Write clean, idiomatic TypeScript code with proper type annotations.
151- Implement error handling and edge cases.
152- Use modern ES6+ features appropriately.
153- For methods with more than one argument, use object destructuring: `function myMethod({ param1, param2 }: MyMethodParams) {...}`.
154 
155### Testing and Documentation
156 
157- Suggest unit tests for critical functions using Vitest and React Testing Library.
158- Provide JSDoc comments for complex functions and types.
159 
160### Performance and Optimization
161 
162- Consider performance implications of your code, especially for larger datasets or complex operations.
163- Suggest optimizations where relevant, explaining the benefits.
164 
165### Reasoning and Explanation
166 
167- Explain your thought process and decisions.
168- If multiple approaches are viable, outline them and explain the pros and cons of each.
169 
170### Continuous Improvement
171 
172  - Use functional and declarative programming patterns; avoid classes.
173  - Prefer iteration and modularization over code duplication.
174  - Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
175  - Structure files: exported component, subcomponents, helpers, static content, types.
176    Naming Conventions
177  - Use lowercase with dashes for directories (e.g., components/auth-wizard).
178  - Favor named exports for components.
179  TypeScript Usage
180  - Use TypeScript for all code; prefer interfaces over types.
181  - Avoid enums; use maps instead.
182  - Use functional components with TypeScript interfaces.
183    Syntax and Formatting
184  - Use the "function" keyword for pure functions.
185  - Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
186  - Never use ReactFC or arrow functions to define components
187  - Use declarative JSX.
188 
189<package_management>
190 
191- Use `pnpm` as the primary package manager for the project
192- Install dependencies using `pnpm add [package-name]`
193- Install dev dependencies using `pnpm add -D [package-name]`
194- Install workspace dependencies using `pnpm add -w [package-name]`
195</package_management>