.cursorrules

Code Style and Structure:

- Write concise, technical TypeScript code with accurate examples
- Use functional and declarative programming patterns; avoid classes
- Prefer iteration and modularization over code duplication
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError)
- Use descriptive function names with auxiliary verbs (e.g., getUserSettings, setUserSettings, checkIsMobile)
- Structure files: exported component, subcomponents, helpers, static content, types
- Use the `~/` alias for imports from the root of the project
- Use the `@this/` alias for imports from packages
- Use the `@this/env` package for environment variables
- Use the `@tooling/*` alias for imports from the `tooling` folder.
- Avoid circular imports

Naming Conventions:

- Use lowercase with dashes for directories (e.g., components/auth-wizard)
- Favor default exports for components, unless exporting multiple things

TypeScript Usage:

- Use TypeScript for all code; prefer types over interfaces
- Avoid enums; use readonly arrays or maps with `as const`
- Use functional components with props and children, and use destructuring for props

Syntax and Formatting:

- Use the "function" keyword for pure functions
- Use the "function" keyword for components
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements
- Use declarative JSX

Error Handling and Validation:

- Prioritize error handling: handle errors and edge cases early
- Use early returns and guard clauses
- Implement proper error logging and user-friendly messages
- Use Zod for form validation. Add the schemas to the `@this/validation` package.
- Return errors from Server Actions to be handled by the UI. Map the errors to the fields.
- Use error boundaries for unexpected errors

UI and Styling:

- Use Shadcn UI, Radix, and Tailwind Aria for components and styling
- Implement responsive design with Tailwind CSS; use a mobile-first approach
- Use the `cn` helper function inside `~/utils/ui` for class name composition

Performance Optimization:

- Minimize 'use client', 'useEffect', and 'setState'; favor React Server Components (RSC)
- Wrap client components in Suspense with fallback
- Use dynamic loading for non-critical components
- Optimize images: use WebP format, include size data, implement lazy loading

Testing:

- We are using Bun for testing. Add your tests to the `__tests__` folder, which should be in the same directory as the file you are testing.
- Import the necessary testing dependencies from "bun:test".
- Use the `test`, `describe`, and `expect` functions for writing tests.
- The `describe` should be named after the function you are testing.
- The `test` should be named after the case you are testing.

Key Conventions:

- Use 'nuqs' for URL search parameter state management
- Optimize Web Vitals (LCP, CLS, FID)
- Limit 'use client':
  - Favor server components and Next.js SSR
  - Use only for Web API access in small components
  - Avoid for data fetching or state management

Follow Next.js docs for Data Fetching, Rendering, and Routing