Cursor rule

1---
2globs:
3  - "packages/hermes-app/**/*.{ts,tsx}"
4---
5 
6# Hermes App - TypeScript/React Rules
7 
8## TypeScript
9 
10### Type Safety
11- Use strict TypeScript settings (`tsconfig.json`)
12- Avoid `any` type - use `unknown` or specific types
13- Define interfaces for all data structures
14- Export types from `src/types/` directory
15 
16### Import Conventions
17- Use absolute imports via path aliases configured in `tsconfig.json`
18- Group imports: React, third-party, local components, types, styles
19- Use named imports over default imports when possible
20 
21## React Patterns
22 
23### Component Structure
24- Prefer functional components with hooks
25- Use TypeScript for props interfaces
26- Export components as named exports
27- Keep components focused and single-purpose
28- Use functional programming patterns, avoid class components
29- Use hooks for state management
30 
31Example structure:
32```typescript
33interface MyComponentProps {
34  title: string;
35  onAction: () => void;
36}
37 
38export function MyComponent({ title, onAction }: MyComponentProps) {
39  // Component logic
40  return <div>{title}</div>;
41}
42```
43 
44### State Management
45- Use React hooks (`useState`, `useEffect`, etc.)
46- TanStack Query for server state
47- Context API for global client state (see `AuthContext`)
48- Custom hooks for reusable logic (see `src/hooks/`)
49 
50## TanStack Router
51 
52### Route Files
53- Place route files in `src/routes/`
54- Follow file-based routing conventions
55- Route files use special naming (e.g., `auth.login.tsx`, `__root.tsx`)
56- Define loaders and error boundaries when needed
57- Use `createFileRoute` for route definitions
58 
59### Navigation
60- Use `<Link>` from `@tanstack/react-router`
61- Use `useNavigate()` hook for programmatic navigation
62- Use type-safe route paths
63 
64## TanStack Query
65 
66### Query Keys
67- Use array-based query keys with hierarchy: `['resource', 'action', ...params]`
68- Example: `['downloads', 'list', { status: 'completed' }]`
69 
70### Hooks Usage
71- Use `useQuery` for fetching data
72- Use `useMutation` for creating/updating/deleting
73- Configure query client in `src/lib/queryClient.ts`
74- Handle loading and error states appropriately
75 
76### Mutations
77- Invalidate relevant queries after mutations
78- Optimistic updates for better UX when appropriate
79- Show toast notifications for success/error states
80 
81## shadcn/ui Components
82 
83### Component Usage
84- Import components from `src/components/ui/`
85- Use composition to build complex components
86- Maintain accessibility (ARIA attributes)
87- Follow shadcn/ui conventions and styling
88 
89### Styling
90- Use Tailwind v4 CSS classes
91- Use `cn()` utility from `src/lib/utils.ts` for conditional classes
92- Follow mobile-first responsive design
93- Use `class-variance-authority` for component variants
94 
95### Theme
96- Support light/dark themes via `next-themes`
97- Access theme via `useTheme()` hook
98- Use CSS variables for theme colors (defined in `style.css`)
99 
100## Custom Hooks
101 
102### Naming
103- All custom hooks must start with `use` prefix
104- Place in `src/hooks/` directory
105- One hook per file with same name as hook
106 
107### Structure
108- Define clear TypeScript return types
109- Include JSDoc comments for complex hooks
110- Compose smaller hooks into larger ones
111- Handle cleanup in `useEffect` return functions
112 
113Examples from codebase:
114- `useConfiguration` - App configuration state
115- `useDownloadActions` - Download queue operations  
116- `useNotifications` - Toast notification system
117- `useKeyboardShortcuts` - Keyboard shortcuts
118 
119## State and Effects
120 
121### useState
122- Initialize with correct types
123- Use functional updates for derived state
124- Consider using `useReducer` for complex state
125 
126### useEffect
127- Declare dependencies accurately
128- Return cleanup functions
129- Avoid unnecessary re-renders
130 
131## API Integration
132 
133### API Client
134- Use centralized API client from `src/services/api/client.ts`
135- Handle authentication tokens automatically
136- Type API responses using interfaces from `src/types/api.ts`
137 
138### Error Handling
139- Catch and display user-friendly error messages
140- Use toast notifications for errors
141- Log errors for debugging
142 
143## Performance
144 
145### Code Splitting
146- Use dynamic imports for large components
147- Leverage Vite's automatic code splitting
148- Lazy load routes when appropriate
149 
150### Memoization
151- Use `useMemo` for expensive computations
152- Use `useCallback` for callback functions passed as props
153- Use `React.memo` for components that re-render frequently
154 
155## Accessibility
156 
157- Use semantic HTML elements
158- Include ARIA labels and roles
159- Ensure keyboard navigation works
160- Test with screen readers
161- Maintain sufficient color contrast
162 
163## Linting and Formatting
164 
165- Run `pnpm lint` before committing
166- Run `pnpm lint:fix` to auto-fix issues
167- ESLint configuration in `eslint.config.js`
168- TypeScript checks: `pnpm type-check`
169