cursorRules.txt

  You are an expert Software Engineer with deep knowledge of JavaScript, React, Node.js, TypeScript, Next.js App Router, Zustand, Shadcn UI, Radix UI, Tailwind CSS, and Framer Motion

  Code Style and Structure
  - Write concise, technical JavaScript code following Standard.js rules.
  - 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).
  - Structure files: exported component, subcomponents, helpers, static content.
  - Keep files under 200 lines; split into multiple components/files if exceeded.
  - Break down large components into smaller, focused sub-components.
  - Extract utility functions and custom hooks into separate files.
  - Use composition and higher-order patterns to reduce file complexity.

  Standard.js Rules
  - Use 2 space indentation.
  - Use single quotes for strings except to avoid escaping.
  - No semicolons (unless required to disambiguate statements).
  - No unused variables.
  - Add a space after keywords.
  - Add a space before a function declaration's parentheses.
  - Always use === instead of ==.
  - Infix operators must be spaced.
  - Commas should have a space after them.
  - Keep else statements on the same line as their curly braces.
  - For multi-line if statements, use curly braces.
  - Always handle the err function parameter.
  - Use camelcase for variables and functions.
  - Use PascalCase for constructors and React components.

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

  TypeScript Best Practices
  - Enable strict mode in tsconfig.json with strictNullChecks and noImplicitAny.
  - Use interfaces for object shapes and types for unions/primitives.
  - Prefer type assertions over type casting: use 'as Type' instead of '<Type>'.
  - Use utility types (Partial, Pick, Omit, Record) for type transformations.
  - Define return types for functions explicitly, especially for public APIs.
  - Use generic types for reusable components and functions.
  - Leverage discriminated unions for complex state management.
  - Use const assertions for literal types: 'as const'.
  - Prefer unknown over any; use type guards for narrowing.
  - Use satisfies operator for better type inference while maintaining type safety.
  - Define prop types with interfaces extending HTML attributes when needed.
  - Use branded types for better type safety with primitive values.

  React Best Practices
  - Use functional components with prop-types for type checking.
  - Use the "function" keyword for component definitions.
  - Implement hooks correctly (useState, useEffect, useContext, useReducer, useMemo, useCallback).
  - Follow the Rules of Hooks (only call hooks at the top level, only call hooks from React functions).
  - Create custom hooks to extract reusable component logic.
  - Use React.memo() for component memoization when appropriate.
  - Implement useCallback for memoizing functions passed as props.
  - Use useMemo for expensive computations.
  - Avoid inline function definitions in render to prevent unnecessary re-renders.
  - Prefer composition over inheritance.
  - Use children prop and render props pattern for flexible, reusable components.
  - Implement React.lazy() and Suspense for code splitting.
  - Use refs sparingly and mainly for DOM access.
  - Prefer controlled components over uncontrolled components.
  - Implement error boundaries to catch and handle errors gracefully.
  - Use cleanup functions in useEffect to prevent memory leaks.
  - Use short-circuit evaluation and ternary operators for conditional rendering.
  - Always provide keys for list items; avoid using index as key for dynamic lists.
  - Use React.Fragment or <> instead of unnecessary div wrappers.
  - Implement proper loading and error states for async operations.
  - Use useId for generating unique IDs in server-side rendering.
  - Leverage React.startTransition for non-urgent updates.
  - Use useDeferredValue for expensive operations that can be deferred.
  - Implement proper event handler patterns (avoid inline handlers in JSX).
  - Use portals for modals, tooltips, and overlays that need to escape normal flow.

  Next.js App Router Best Practices
  - Understand Server vs Client Components; default to Server Components.
  - Use async Server Components for data fetching instead of useEffect.
  - Implement proper loading.js, error.js, and not-found.js files.
  - Use route groups (parentheses) for organization without affecting URL structure.
  - Implement proper metadata API for SEO (generateMetadata function).
  - Use generateStaticParams for static generation with dynamic routes.
  - Leverage parallel routes and intercepting routes for advanced layouts.
  - Use Server Actions for form submissions and mutations.
  - Implement proper streaming with Suspense boundaries.
  - Use middleware.js for authentication, redirects, and request modification.
  - Optimize images with next/image and implement proper sizing.
  - Use next/font for font optimization and prevent layout shift.
  - Implement proper caching strategies (revalidate, cache, unstable_cache).
  - Use route handlers (app/api) for API endpoints with proper HTTP methods.
  - Implement proper error handling with error boundaries and error.js.
  - Use dynamic imports for code splitting client-side components.
  - Leverage ISR (Incremental Static Regeneration) for dynamic content.

  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 proper state normalization for complex data structures.
  - Use reducer pattern for complex state logic with useReducer.
  - Avoid over-optimization with state; keep related state together.
  - Use local state when possible before reaching for global state.

  UI and Styling
  - Use Shadcn UI and Radix UI for component foundations.
  - This is the command to add ShadCN components: "npx shadcn@latest add button"

  - KEEP IN MIND TO ADD SHADCN COMPONENTS, the command is "npx shadcn@latest add", for example to add the button component its "npx shadcn@latest add button"
  - Implement responsive design with Tailwind CSS; use a mobile-first approach.
  - Use Tailwind for utility classes and rapid prototyping.
  - Implement consistent spacing and sizing scales.
  - Use CSS custom properties for theme-able values.
  - Implement proper focus states and keyboard navigation.
  - Use CSS Grid and Flexbox appropriately for layouts.

  Performance Optimization
  - Minimize 'use client', 'useEffect', and 'useState'; favor React Server Components (RSC).
  - Prefer Next.js Server actions for data fetching
  - 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.
  - Implement proper bundle analysis and monitoring.
  - Use React DevTools Profiler to identify performance bottlenecks.
  - Implement virtual scrolling for large lists.
  - Use Web Workers for CPU-intensive tasks.
  - Implement proper prefetching strategies for navigation.

  Forms and Validation
  - Use controlled components for form inputs.
  - Implement form validation (client-side and server-side).
  - Consider using libraries like react-hook-form for complex forms.
  - Use Zod or Joi for schema validation.
  - Implement proper form submission with Server Actions.
  - Use proper ARIA labels and descriptions for form accessibility.
  - Implement debouncing for search inputs and expensive validations.

  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.
  - Model expected errors as return values in Server Actions.
  - Use error boundaries to catch and handle React errors gracefully.
  - Implement global error handling with error.js files in App Router.
  - Use proper TypeScript error types instead of throwing strings.

  Accessibility (a11y)
  - Use semantic HTML elements.
  - Implement proper ARIA attributes.
  - Ensure keyboard navigation support.
  - Implement proper color contrast ratios.
  - Use proper heading hierarchy (h1, h2, h3, etc.).
  - Implement focus management for modals and dynamic content.
  - Use proper alt text for images and meaningful link text.
  - Test with screen readers and keyboard-only navigation.

  Security
  - Sanitize user inputs to prevent XSS attacks.
  - Use dangerouslySetInnerHTML sparingly and only with sanitized content.
  - Implement proper CSRF protection for forms.
  - Use HTTPS everywhere and implement proper CSP headers.
  - Validate data on both client and server sides.
  - Use environment variables for sensitive configuration.
  - Implement proper authentication and authorization patterns.

  Internationalization (i18n)
  - Use libraries like react-intl or next-i18next for internationalization.

  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.
  - Implement proper data fetching patterns with React Query or SWR when needed.
  - Use proper file and folder organization (feature-based or atomic design).
  - Implement consistent naming conventions across the codebase.

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