Next.js React TypeScript Best Practices: Cursor Rules for Shadcn UI, Tailwind & Viem

1. **Adopt Functional and Declarative Coding Style**: Build with pure functions, avoiding classes entirely. Prioritize loops and code reuse through modular components to eliminate repetition. Choose clear variable names incorporating helper verbs like 'isActive' or 'hasError' for better readability.

2. **Organize File and Directory Structure**: Name directories in lowercase with hyphens (e.g., 'user-profile'). Export components by name. Structure files sequentially: main component first, followed by sub-components, utility functions, static data, and TypeScript interfaces at the bottom.

3. **Leverage TypeScript Best Practices**: Write all code in TypeScript, favoring interfaces over type aliases. Replace enums with object maps for flexibility. Declare pure functions using the 'function' keyword and skip semicolons. Simplify conditionals by omitting braces for single-line blocks and using inline syntax like 'if (check) execute()'.

4. **Implement Robust Error Handling Early**: Start functions by checking preconditions with guard clauses and early returns to flatten code structure. Reserve the main success logic for the end. Eliminate redundant 'else' blocks. Log errors comprehensively, display user-friendly messages, and create reusable error classes for uniformity.

5. **Optimize React and Next.js Components**: Develop functional components with TypeScript interfaces and declarative JSX. Define components as functions rather than const declarations. Integrate Shadcn UI, Radix primitives, and Tailwind Aria for styling. Apply mobile-first responsive designs via Tailwind classes.

6. **Minimize Client-Side Dependencies**: Limit 'use client' directives to essential interactive elements. Prefer React Server Components (RSC) for rendering and data access. Avoid useEffect and local state where possible; rely on Next.js App Router for navigation and state updates.

7. **Enhance Forms and Validation**: Use Zod schemas for input validation paired with react-hook-form and useActionState. For server actions, employ next-safe-action to ensure type safety, Zod input checks, and consistent ActionResponse outputs including errors and success states.

8. **Prioritize Performance and UX**: Wrap async client components in Suspense with loading fallbacks. Dynamically import non-essential modules. Optimize images with WebP, appropriate sizing, and lazy attributes. Focus on Core Web Vitals like LCP and CLS. Use error.tsx and global-error.tsx for boundary handling of unexpected issues.

9. **Standardize Server Actions and Services**: In services directory, throw descriptive errors catchable by TanStack Query for user display. Model predictable errors as action return values, skipping try/catch. Always return structured ActionResponse types.

10. **Follow App Router Conventions**: Drive state changes via Next.js routing features. Fetch data server-side, minimizing client hydration. Consult official docs for rendering, caching, and streaming patterns to maximize SSR benefits.