Cursor rule

1---
2description: Next.js development standards and patterns
3globs: "app/**/*.{ts,tsx}"
4---
5 
6# Next.js Rules
7 
8## **Core Principles**
9- **Default to Server Components** for better performance.
10- **Minimize `'use client'` directives** to leverage SSR benefits.
11- Follow **App Router patterns and conventions**.
12- **Handle errors properly** using `error.tsx` and **error boundaries**.
13- Use **Next.js 15 built-in components** (`Image`, `Link`, `Script`, `Head`, etc.).
14- Optimize **Web Vitals** (`LCP`, `CLS`, `FID`).
15 
16### **Key Conventions**
17- Use **`nuqs`** for URL search parameter state management.
18- **Limit `'use client'`**:
19  - Favor **Server Components** and **Next.js SSR**.
20  - Use only for **Web API access in small components**.
21  - Avoid for **data fetching or state management**.
22 
23---
24 
25## **Component Architecture**
26```tsx
27// Prefer Server Components by default
28export function ServerComponent() {
29  return (
30    <section className="space-y-4">
31      <h1>Server Rendered</h1>
32      <ClientComponent />
33    </section>
34  )
35}
36 
37// Use 'use client' only when necessary
38'use client'
39function ClientComponent() {
40  const [state, setState] = useState(false)
41  return <button onClick={() => setState(!state)}>Toggle</button>
42}
43```
44 
45---
46 
47## **Data Fetching**
48- **Use Server Components** for data fetching.
49- **Implement proper caching strategies**.
50- **Handle loading and error states**.
51- **Use revalidation patterns** to optimize freshness.
52 
53---
54 
55## **Server Actions**
56```tsx
57'use server'
58import { type ActionResult, success, failure } from '@chaingraph/next'
59import { createSafeActionClient } from 'next-safe-action'
60 
61export const saveAction = createSafeActionClient()
62  .schema(actionSchema)
63  .action(async ({ parsedInput }): Promise<ActionResult<T>> => {
64    try {
65      // Happy path
66      return success(result)
67    } catch (error) {
68      return failure({
69        code: 'UNEXPECTED_ERROR',
70        error,
71        label: 'saveAction'
72      })
73    }
74  })
75```
76 
77---
78 
79## **Performance Patterns**
80```tsx
81// Use Image component with proper sizing
82import { Image } from 'next/image'
83 
84export function OptimizedImage() {
85  return (
86    <Image
87      src="/hero.webp"
88      alt="Hero"
89      width={1200}
90      height={630}
91      priority={true}
92      className="w-full"
93    />
94  )
95}
96 
97// Use Suspense for loading states
98export function LazyComponent() {
99  return (
100    <Suspense fallback={<LoadingSkeleton />}>
101      <ExpensiveComponent />
102    </Suspense>
103  )
104}
105```
106 
107---
108 
109## **Next.js Optimizations**
110- **Use App Router** with `nuqs` for efficient navigation and state management.
111- **Implement streaming** with `Suspense` for progressive loading.
112- **Follow proper caching strategies**:
113  - Use `fetch` cache options appropriately.
114  - Implement **revalidation when needed**.
115- **Minimize `'use client'`**, `'useEffect'`, and `'setState'` in favor of **React Server Components (RSC)**.
116- **Wrap client components** in `Suspense` with a fallback.
117- **Use dynamic loading** for non-critical components.
118- **Optimize images**:
119  - Use **WebP format**.
120  - Include **size data**.
121  - Implement **lazy loading**.
122 
123---
124 
125## **UI & Styling**
126- **Use Shadcn UI, Radix, and Tailwind** for components and styling.
127- **Implement responsive design** with **Tailwind CSS** using a **mobile-first approach**.
128