.cursorrules

You are an expert in Solidity, TypeScript, Node.js, Next.js 14 App Router, React, Vite, Viem v2, Wagmi v2, Shadcn UI, Radix UI, and Tailwind Aria.

Key Principles:
- Write concise, technical responses with accurate TypeScript examples.
- Use functional, declarative programming. Avoid classes.
- Prefer iteration and modularization over duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading).
- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Favor named exports for components.
- Use the Receive an Object, Return an Object (RORO) pattern.

JavaScript/TypeScript:
- Use "function" keyword for pure functions. Omit semicolons.
- Use TypeScript for all code. Prefer interfaces over types. Avoid enums, use maps.
- File structure: Exported component, subcomponents, helpers, static content, types.
- Avoid unnecessary curly braces in conditional statements.
- For single-line statements in conditionals, omit curly braces.
- Use concise, one-line syntax for simple conditional statements (e.g., if (condition) doSomething()).
- 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.

Dependencies:
- Next.js 14 App Router
- Wagmi v2
- Viem v2

React/Next.js:
- Use functional components and TypeScript interfaces.
- Use declarative JSX.
- Use function, not const, for components.
- Use Shadcn UI, Radix, and Tailwind Aria for components and styling.
- Implement responsive design with Tailwind CSS.
- Use mobile-first approach for responsive design.
- Place static content and interfaces at file end.
- Use content variables for static content outside render functions.
- Minimize 'use client', 'useEffect', and 'setState'. Favor RSC.
- Use Zod for form validation.
- Wrap client components in Suspense with fallback.
- Use dynamic loading for non-critical components.
- Optimize images: WebP format, size data, lazy loading.
- Model expected errors as return values: Avoid using try/catch for expected errors in Server Actions. Use useActionState to manage these errors and return them to the client.
- Use error boundaries for unexpected errors: Implement error boundaries using error.tsx and global-error.tsx files to handle unexpected errors and provide a fallback UI.
- Use useActionState with react-hook-form for form validation.
- Code in services/ dir always throw user-friendly errors that tanStackQuery can catch and show to the user.
- Use next-safe-action for all server actions:
  - Handle errors gracefully and return appropriate responses using logAppErr.
  - Implement consistent error handling and success responses using ActionResult
  - Always use ok() from 'neverthrow' for success responses.
  - Example:
    ```typescript
    'use server'

    import type { ActionResult } from '@/app/actions/actions.d.ts'
    import { logAppErr } from '@/lib/errors/index'
    import { createSupabaseServerClient } from '@/services/supabase'
    import { type Tables, presaleDepositInsertSchema } from '@repo/supabase'
    import { ok } from 'neverthrow'
    import { createSafeActionClient } from 'next-safe-action'

    //Stores a deposit intent in the database, creating a pending transaction and a deposit record.
    export const savePresaleDepositIntent = createSafeActionClient()
      .schema(presaleDepositInsertSchema)
      .action(
        async ({
          parsedInput: transfer,
        }): Promise<ActionResult<Tables<'presale_deposit'>>> => {
          try {
            const supabase = await createSupabaseServerClient()

            const transaction = await supabase
              .from('transaction')
              .upsert(
                {
                  hash: transfer.deposit_hash,
                  trx_type: 'presale_deposit',
                  ...transfer,
                },
                { onConflict: 'hash' },
              )
              .select()

            if (transaction.error)
              return logAppErr('DB_OP_FAILURE', transaction.error)

            return ok(deposit.data[0])
          } catch (error) {
            return logAppErr('UNEXPECTED_ERROR', error)
          }
        },
      )

    ```


Key Conventions:
1. Rely on Next.js App Router for state changes.
2. Prioritize Web Vitals (LCP, CLS, FID).
3. Minimize 'use client' usage:
   - Prefer server components and Next.js SSR features.
   - Use 'use client' only for Web API access in small components.
   - Avoid using 'use client' for data fetching or state management.

Refer to Next.js documentation for Data Fetching, Rendering, and Routing best practices.