Cursor rule

1---
2description: Typescript Rules
3globs: *.ts, *.tsx
4alwaysApply: false
5---
6You are an expert in TypeScript, Node.js, Vite, Vitest, Inertia.js, React, Mantine, TanStack Query, CSS, HTML, UI and UX.
7 
8You are BANNED from using `any`!
9You are BANNED from typecasting to bypass typescript issues!
10 
11## Code Style and Structure
12 
13- Use functional and declarative programming patterns; avoid classes.
14- Prefer iteration and modularization over code duplication.
15- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
16- Consider edge cases and error scenarios, for simple edge cases, use the "return early" pattern to avoid nesting.
17- Properly structure files, all frontend code goes in /app/frontend
18  - /app/frontend/components for all general purpose, highly reusable components.
19  - /app/frontend/features for all feature specific components.
20  - /app/frontend/layouts for all layout components.
21  - /app/frontend/lib for all non-react code.
22  - /app/frontend/pages for all top-level Inertia pages. These components are the entry point for each route from the server.
23  - /app/frontend/queries for all async react-query methods, following the convention and type definitions in /app/frontend/queries/index.ts.
24  - /app/frontend/types for any globally used types or interfaces, or any custom types used in serializers. (Do no modify anything in types/serializers as it is all auto generated)
25 
26  ### TypeScript Usage
27 
28  - Use TypeScript for all javascript code; prefer interfaces over types.
29  - Write concise, technical TypeScript code with accurate examples.
30  - Avoid enums; use maps instead.
31  - Use functional components with TypeScript interfaces.
32  - Apply generics to functions, actions, and slices where type flexibility is needed.
33  - Utilize TypeScript utility types (Partial, Pick, Omit) for cleaner and reusable code.
34  - Prefer interface over type for defining object structures, especially when extending.
35  - Use mapped types for creating variations of existing types dynamically.
36  - DO NOT USE `any`, ever! If a specific type definition can't be derived, use `unknown`, but only as a last resort.
37 
38  ### React Component Architecture
39 
40  - Use functional components with TypeScript interfaces.
41  - Define components using `const`.
42  - Extract reusable logic into custom hooks.
43  - Implement proper component composition.
44  - Implement proper cleanup in `useEffect` hooks.
45 
46  ### React Performance Optimization
47 
48  - Use `useCallback` for memoizing expensive callback functions.
49  - Implement `useMemo` for expensive computations.
50  - Avoid inline function definitions in JSX.
51  - Implement code splitting using dynamic imports.
52  - Implement proper key props in lists (avoid using index as key).
53  
54  ### Variable and Function Naming Patterns
55 
56  - Prefix event handlers with 'handle': handleClick, handleSubmit
57  - Prefix boolean variables with verbs: isLoading, hasError, canSubmit
58  - Prefix custom hooks with 'use': useAuth, useForm
59  - Use complete words over abbreviations except for:
60    - err (error)
61    - req (request)
62    - res (response)
63    - props (properties)
64    - ref (reference)
65    - config (configuration)
66 
67  ### File Naming Conventions
68 
69  - Use lowercase with dashes for directories (e.g., components/auth-wizard).
70  - Favor named exports for components.
71 
72## Syntax and Formatting
73 
74- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
75- Use declarative JSX.
76 
77## Testing
78 
79- Write tests using Vitest and React-Testing-Library and Playwright.
80- Put test files in app/frontend/tests in a folder structure which matches the file's location.
81 
82  ### Unit Testing
83 
84  - Write thorough unit tests to validate individual functions and components.
85  - Use Vitest and React Testing Library for reliable and efficient testing of React components.
86  - Follow patterns like Arrange-Act-Assert to ensure clarity and consistency in tests.
87  - Mock external dependencies and API calls to isolate unit tests.
88 
89  ### Integration Testing
90 
91  - Focus on user workflows to ensure app functionality.
92  - Set up and tear down test environments properly to maintain test independence.
93  - Use snapshot testing selectively to catch unintended UI changes without over-relying on it.
94  - Leverage testing utilities (e.g., screen in RTL) for cleaner and more readable tests.
95 
96  ### E2E Testing
97 
98  - Use Playwright to write end to end tests, putting test files in app/frontend/tests/e2e.
99  - Don't mock the server, assume that the server will be running in a test environment when running e2e tests.
100 
101## Accessibility (a11y)
102 
103- Rely primarily on existing accessibility in Mantine.
104- Use semantic HTML for meaningful structure.
105- Apply accurate ARIA attributes where needed.
106- Ensure full keyboard navigation support.
107- Manage focus order and visibility effectively.
108- Maintain accessible color contrast ratios.
109- Follow a logical heading hierarchy.
110- Make all interactive elements accessible.
111- Provide clear and accessible error feedback.
112 
113## Internationalization (i18n)
114 
115- Use next-i18next to load translations in components.
116- Translation json files are generated by the i18n-js gem, do not modify them directly. Translations are defined in the Rails locales folder in yml files.
117- Implement proper locale detection.
118- Use proper number and date formatting.
119- Use proper currency formatting.
120- Implement proper RTL support.
121 
122## UI and Styling
123 
124- Use proxied Mantine components for styling. Mantine proxy files are located in app/frontend/components.
125- Use CSS modules for styling, name CSS files using the same name as the root component with the extension `.css.ts`. CSS module files use Linaria and should import the "css" method from `@/lib`.
126- Implement responsive design; use a mobile-first approach.
127- Use Mantine's dark mode methods for implementing visual themes in CSS files.
128- Always use `clsx` to wrap CSS classes passed to a `className` prop
129 
130## Global State
131 
132- Use zustand for global state.
133- Don't store values in global state unless they are truly frontend only. Most state should be managed on the server.
134- Avoid large, all-encompassing slices; separate concerns by feature.
135 
136## Performance Optimization
137 
138- Minimize `useEffect`, and `setState`.
139- Wrap client components in Suspense with fallback.
140- Optimize images: use WebP format, include size data, implement lazy loading.
141 
142