{"filename":"react-typescript-nextjs-nodejs-cursorrules-prompt-.mdc","content":"---\ndescription: \"Cursor rules for React development with TypeScript, Next.js, and Node.js integration.\"\nglobs: **/*\nalwaysApply: false\n---\nYou 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.\n\nKey Principles:\n\n- Write concise, technical responses with accurate TypeScript examples.\n- Use functional, declarative programming. Avoid classes.\n- Prefer iteration and modularization over duplication.\n- Use descriptive variable names with auxiliary verbs (e.g., isLoading).\n- Use lowercase with dashes for directories (e.g., components/auth-wizard).\n- Favor named exports for components.\n- Use the Receive an Object, Return an Object (RORO) pattern.\n\nJavaScript/TypeScript:\n\n- Use \"function\" keyword for pure functions. Omit semicolons.\n- Use TypeScript for all code. Prefer interfaces over types. Avoid enums, use maps.\n- File structure: Exported component, subcomponents, helpers, static content, types.\n- Avoid unnecessary curly braces in conditional statements.\n- For single-line statements in conditionals, omit curly braces.\n- Use concise, one-line syntax for simple conditional statements (e.g., if (condition) doSomething()).\n- Prioritize error handling and edge cases:\n  - Handle errors and edge cases at the beginning of functions.\n  - Use early returns for error conditions to avoid deeply nested if statements.\n  - Place the happy path last in the function for improved readability.\n  - Avoid unnecessary else statements; use if-return pattern instead.\n  - Use guard clauses to handle preconditions and invalid states early.\n  - Implement proper error logging and user-friendly error messages.\n  - Consider using custom error types or error factories for consistent error handling.\n\nDependencies:\n\n- Next.js 14 App Router\n- Wagmi v2\n- Viem v2\n\nReact/Next.js:\n\n- Use functional components and TypeScript interfaces.\n- Use declarative JSX.\n- Use function, not const, for components.\n- Use Shadcn UI, Radix, and Tailwind Aria for components and styling.\n- Implement responsive design with Tailwind CSS.\n- Use mobile-first approach for responsive design.\n- Place static content and interfaces at file end.\n- Use content variables for static content outside render functions.\n- Minimize 'use client', 'useEffect', and 'setState'. Favor RSC.\n- Use Zod for form validation.\n- Wrap client components in Suspense with fallback.\n- Use dynamic loading for non-critical components.\n- Optimize images: WebP format, size data, lazy loading.\n- 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.\n- 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.\n- Use useActionState with react-hook-form for form validation.\n- Code in services/ dir always throw user-friendly errors that tanStackQuery can catch and show to the user.\n- Use next-safe-action for all server actions:\n  - Implement type-safe server actions with proper validation.\n  - Utilize the `action` function from next-safe-action for creating actions.\n  - Define input schemas using Zod for robust type checking and validation.\n  - Handle errors gracefully and return appropriate responses.\n  - Use import type { ActionResponse } from '@/types/actions'\n  - Ensure all server actions return the ActionResponse type\n  - Implement consistent error handling and success responses using ActionResponse\n  - Example:\n    ```typescript\n    'use server'\n    import { createSafeActionClient } from 'next-safe-action'\n    import { z } from 'zod'\n    import type { ActionResponse } from '@/app/actions/actions'\n    const schema = z.object({\n      value: z.string()\n    })\n    export const someAction = createSafeActionClient()\n      .schema(schema)\n      .action(async (input): Promise => {\n        try {\n          // Action logic here\n          return { success: true, data: /* result */ }\n        } catch (error) {\n          return { success: false, error: error instanceof AppError ? error : appErrors.UNEXPECTED_ERROR, }\n        }\n      })\n    ```\n\nKey Conventions:\n\n1. Rely on Next.js App Router for state changes.\n2. Prioritize Web Vitals (LCP, CLS, FID).\n3. Minimize 'use client' usage:\n  - Prefer server components and Next.js SSR features.\n  - Use 'use client' only for Web API access in small components.\n  - Avoid using 'use client' for data fetching or state management.\n\nRefer to Next.js documentation for Data Fetching, Rendering, and Routing best practices.\n"}