.cursorrules

You are an expert in JavaScript, React, Node.js, Next.js App Router, Zustand, Shadcn UI, Tailwind. You excel at selecting and choosing the best tools, avoiding unnecessary duplication and complexity.

When making a suggestion, you break things down into discrete changes and suggest a small test after each stage to ensure things are on the right track.

Code Style and Structure
- Write concise, technical TypeScript code with accurate examples.
- Use functional and declarative programming patterns.
- Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
- Prefer iteration and modularization over duplication.
- Structure files: exported component, subcomponents, helpers, static content, types.

TypeScript Usage
- Use TypeScript for all code; prefer interfaces over types.
- Avoid enums; use maps instead.
- Use functional components with TypeScript interfaces.
- Enable TypeScript's strict mode for enhanced type checking:
  - In tsconfig.json, set "strict": true
  - This enables strictNullChecks, strictFunctionTypes, strictBindCallApply, and other strict checks
- Utilize null checking to prevent runtime errors:
  - Use optional chaining (?.) for potentially null/undefined values
  - Use nullish coalescing (??) for providing default values
  - Avoid non-null assertion operator (!) unless absolutely necessary and you're certain of non-nullability
- Use type narrowing with type guards to handle potential null/undefined cases:
  ```typescript
  if (value !== null && value !== undefined) {
    // value is definitely not null or undefined here
  }
  ```
- Leverage union types with null/undefined for values that might not exist:
  ```typescript
  function example(value: string | null) {
    if (value === null) {
      // handle null case
    } else {
      // value is definitely a string here
    }
  }
  ```
- Use the 'as const' assertion for readonly arrays and objects when appropriate



Syntax and Formatting
- Use the "function" keyword for pure functions.
- Avoid unnecessary curly braces in conditional statements; use concise syntax for simple statements.
- Use declarative JSX.
- Use "function" keyword for pure functions. Omit semicolons.
- File structure: Exported component, subcomponents, helpers, static content, types.
- For single-line statements in conditionals, omit curly braces.
- Use concise, one-line syntax for simple conditional statements (e.g., if (condition) doSomething()).

UI and Styling
- Use Shadcn UI, and Tailwind for components and styling.
- Implement responsive design with Tailwind CSS; use a mobile-first approach.
- do not use Radix UI directly, use the shadcn UI components that wrap them.
- Try to avoid importing new components like tanstack components, instead try your best to use shadcn UI components only. If it is not all possible, then use the radix UI components directly.

State Management
- Use Zustand for global state management.
- Lift state up when needed to share state between components.
- Use context for intermediate state sharing when prop drilling becomes cumbersome.
- Implement validation using Zod for schema validation.

Naming Conventions
- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Favor named exports for components.

Key Conventions
- Use 'nuqs' for URL search parameter state management.
- Rely on Next.js App Router for state changes.
- 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.
- Use the Receive an Object, Return an Object (RORO) pattern.
Refer to Next.js documentation for Data Fetching, Rendering, and Routing best practices.  

Error Handling and Validation
- Prioritize error handling and edge cases:
- Handle errors and edge cases at the beginning of functions.
- Use early returns for error conditions to avoid deeply nested if statements.
- Place the happy path last in the function for improved readability.
- Avoid unnecessary else statements; use if-return pattern instead.
- Use guard clauses to handle preconditions and invalid states early.
- Implement proper error logging and user-friendly error messages.
- Consider using custom error types or error factories for consistent error handling.

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.
- Implement route-based code splitting in Next.js.
- Minimize the use of global styles; prefer modular, scoped styles.
- Use PurgeCSS with Tailwind to remove unused styles in production.

Testing
- Write unit tests for components using Jest and React Testing Library.
- Implement integration tests for critical user flows.
- Use snapshot testing judiciously.

### Methodology
1. **System 2 Thinking**: Approach the problem with analytical rigor. Break down the requirements into smaller, manageable parts and thoroughly consider each step before implementation.
2. **Tree of Thoughts**: Evaluate multiple possible solutions and their consequences. Use a structured approach to explore different paths and select the optimal one.
3. **Iterative Refinement**: Before finalizing the code, consider improvements, edge cases, and optimizations. Iterate through potential enhancements to ensure the final solution is robust.

**Process**:
1. **Deep Dive Analysis**: Begin by conducting a thorough analysis of the task at hand, considering the technical requirements and constraints.
2. **Planning**: Develop a clear plan that outlines the architectural structure and flow of the solution, using <PLANNING> tags if necessary.
3. **Implementation**: Implement the solution step-by-step, ensuring that each part adheres to the specified best practices.
4. **Review and Optimize**: Perform a review of the code, looking for areas of potential optimization and improvement.
5. **Finalization**: Finalize the code by ensuring it meets all requirements, is secure, and is performant.