Cursor rule

1---
2description: TypeScript type definitions and utility patterns for the application
3globs: ["src/lib/types.ts", "src/lib/utils.ts", "src/lib/constants.ts"]
4alwaysApply: false
5---
6 
7# TypeScript & Utilities Rules
8 
9## Shared Type Definitions
10 
11### Core Application Types
12```tsx
13// lib/types.ts - Always define shared types here
14export interface User {
15  id: string
16  email: string
17  name: string
18  avatar?: string
19  role: UserRole
20  createdAt: string
21  updatedAt: string
22}
23 
24export interface ApiResponse<T> {
25  data: T
26  message: string
27  success: boolean
28  meta?: {
29    total: number
30    page: number
31    limit: number
32  }
33}
34 
35export type UserRole = 'admin' | 'user' | 'guest'
36export type Theme = 'light' | 'dark' | 'system'
37export type LoadingState = 'idle' | 'loading' | 'success' | 'error'
38```
39 
40### Form Type Patterns
41```tsx
42// Derive form types from Zod schemas
43export type UserFormData = z.infer<typeof userSchema>
44export type CreateUserData = z.infer<typeof createUserSchema>
45export type UpdateUserData = z.infer<typeof updateUserSchema>
46 
47// Component prop types
48export interface UserCardProps {
49  user: User
50  onEdit: (id: string) => void
51  onDelete: (id: string) => void
52  className?: string
53}
54```
55 
56## Utility Functions
57 
58### Keep Existing cn Function
59```tsx
60// lib/utils.ts - NEVER modify this function
61export function cn(...inputs: ClassValue[]) {
62  return twMerge(clsx(inputs))
63}
64```
65 
66### Common Utility Patterns
67```tsx
68// Date formatting
69export function formatDate(date: Date | string, format?: string): string {
70  return new Intl.DateTimeFormat('en-US', {
71    year: 'numeric',
72    month: 'short',
73    day: 'numeric',
74    ...format
75  }).format(new Date(date))
76}
77 
78// Debounce utility
79export function debounce<T extends (...args: any[]) => any>(
80  func: T,
81  wait: number
82): (...args: Parameters<T>) => void {
83  let timeout: NodeJS.Timeout
84  return (...args: Parameters<T>) => {
85    clearTimeout(timeout)
86    timeout = setTimeout(() => func(...args), wait)
87  }
88}
89 
90// Sleep utility for demos/testing
91export const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
92```
93 
94## Constants Organization
95 
96### API and Route Constants
97```tsx
98// lib/constants.ts
99export const API_ENDPOINTS = {
100  USERS: '/api/users',
101  PRODUCTS: '/api/products',
102  AUTH: '/api/auth',
103} as const
104 
105export const QUERY_KEYS = {
106  USERS: 'users',
107  PRODUCTS: 'products',
108  USER_PROFILE: 'user-profile',
109} as const
110 
111export const ROUTES = {
112  HOME: '/',
113  DASHBOARD: '/dashboard',
114  USERS: '/users',
115  PROFILE: '/profile',
116} as const
117```
118 
119### Configuration Constants
120```tsx
121export const APP_CONFIG = {
122  APP_NAME: 'My App',
123  API_BASE_URL: import.meta.env.VITE_API_URL || 'http://localhost:3000',
124  ITEMS_PER_PAGE: 10,
125  MAX_FILE_SIZE: 5 * 1024 * 1024, // 5MB
126} as const
127 
128export const BREAKPOINTS = {
129  sm: '640px',
130  md: '768px',
131  lg: '1024px',
132  xl: '1280px',
133  '2xl': '1536px',
134} as const
135```
136 
137## TypeScript Best Practices
138 
139### Generic Patterns
140```tsx
141// API response wrapper
142export interface PaginatedResponse<T> {
143  data: T[]
144  meta: {
145    total: number
146    page: number
147    limit: number
148    totalPages: number
149  }
150}
151 
152// Generic hook return type
153export interface UseQueryResult<T> {
154  data: T | undefined
155  isLoading: boolean
156  error: Error | null
157  refetch: () => void
158}
159```
160 
161### Environment Variables Typing
162```tsx
163// vite-env.d.ts additions
164interface ImportMetaEnv {
165  readonly VITE_API_URL: string
166  readonly VITE_APP_NAME: string
167  // Add more environment variables as needed
168}
169 
170interface ImportMeta {
171  readonly env: ImportMetaEnv
172}
173```
174 
175## Type Anti-Patterns
176- Using `any` type
177- Inline interface definitions in components
178- Not leveraging Zod for runtime validation
179- Duplicate type definitions across files
180 
181## Type Best Practices
182- Define shared types in `lib/types.ts`
183- Use Zod schemas for validation and type inference
184- Leverage TypeScript strict mode
185- Use proper generic constraints
186