.cursorrules (deprecated)

1# Next.js 14+ App Router — Cursor Rules
2# Comprehensive rules for Next.js applications using the App Router
3 
4## Project Context
5You are working on a Next.js 14+ application using the App Router (app/ directory).
6The project leverages React Server Components by default, with Client Components used
7selectively. Server Actions handle mutations. The codebase follows Next.js conventions
8for file-based routing, layouts, and data fetching.
9 
10## Tech Stack
11- Next.js 14+ with App Router
12- React 18+ (Server Components by default)
13- TypeScript (strict mode)
14- Tailwind CSS for styling
15- Prisma or Drizzle for database ORM
16- NextAuth.js / Auth.js for authentication
17- Vercel for deployment (or self-hosted)
18 
19## Coding Style
20 
21### Naming Conventions
22- Route files: `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx`
23- Server Actions: `actions.ts` in the route segment or `src/actions/`
24- API Routes: `route.ts` in `app/api/` segments
25- Components: PascalCase files matching component name
26- Utilities: camelCase in `src/lib/`
27 
28### File Structure
29```
30app/
31  (marketing)/          # Route groups for layout segmentation
32    page.tsx
33    layout.tsx
34  (dashboard)/
35    layout.tsx
36    settings/
37      page.tsx
38  api/
39    webhooks/
40      route.ts
41src/
42  components/
43    ui/                 # Shared UI primitives
44    forms/              # Form components
45  lib/
46    db.ts               # Database client
47    auth.ts             # Auth configuration
48    utils.ts            # Utility functions
49  actions/              # Server Actions
50  types/                # Shared TypeScript types
51```
52 
53## Server vs Client Components
54 
55### Server Components (default — no directive needed)
56- Data fetching directly in the component (async/await)
57- Access to backend resources (database, file system, env secrets)
58- Large dependencies that should stay on the server
59- Static content that doesn't need interactivity
60- Components that pass data down to Client Components
61 
62### Client Components (add `'use client'` directive)
63- Interactive UI (onClick, onChange, onSubmit handlers)
64- Browser APIs (localStorage, window, navigator)
65- React hooks (useState, useEffect, useContext, useReducer)
66- Third-party libraries that use browser APIs
67- Components that depend on user interaction state
68 
69### Rules
70- Default to Server Components. Only add `'use client'` when you need interactivity.
71- Push `'use client'` boundary as far down the tree as possible.
72- Never import a Server Component into a Client Component — pass as children instead.
73- Never use `'use server'` inside a Client Component file.
74- Keep client bundles small — extract static parts into Server Components.
75 
76## Data Fetching
77 
78### Server Components
79```tsx
80// Fetch data directly — no useEffect needed
81async function ProductPage({ params }: { params: { id: string } }) {
82  const product = await db.product.findUnique({ where: { id: params.id } });
83  if (!product) notFound();
84  return <ProductDetail product={product} />;
85}
86```
87 
88### Caching and Revalidation
89- Use `fetch()` with `next: { revalidate: 3600 }` for time-based revalidation
90- Use `revalidatePath()` or `revalidateTag()` in Server Actions for on-demand revalidation
91- Mark dynamic pages with `export const dynamic = 'force-dynamic'` when needed
92- Use `unstable_cache()` for non-fetch data sources (database queries)
93- Understand the caching layers: Request Memoization → Data Cache → Full Route Cache
94 
95### Server Actions
96```tsx
97'use server'
98 
99import { revalidatePath } from 'next/cache';
100import { redirect } from 'next/navigation';
101import { z } from 'zod';
102 
103const CreatePostSchema = z.object({
104  title: z.string().min(1).max(200),
105  content: z.string().min(1),
106});
107 
108export async function createPost(formData: FormData) {
109  const validated = CreatePostSchema.safeParse({
110    title: formData.get('title'),
111    content: formData.get('content'),
112  });
113 
114  if (!validated.success) {
115    return { error: validated.error.flatten().fieldErrors };
116  }
117 
118  await db.post.create({ data: validated.data });
119  revalidatePath('/posts');
120  redirect('/posts');
121}
122```
123 
124## Error Handling
125- Use `error.tsx` boundary files for route segment error handling
126- Use `not-found.tsx` for 404 states triggered by `notFound()`
127- Use `loading.tsx` for streaming/Suspense loading states
128- Validate all Server Action inputs with Zod or similar
129- Return structured error objects from Server Actions, don't throw
130- Use `global-error.tsx` in app root for root layout errors
131- Log server errors to an error tracking service (Sentry, etc.)
132 
133## Route Configuration
134- `generateStaticParams()` for static generation of dynamic routes
135- `generateMetadata()` for dynamic SEO metadata per route
136- Route groups `(groupName)` for layout organization without affecting URL
137- Parallel routes `@slotName` for simultaneous rendering
138- Intercepting routes `(.)` `(..)` for modal patterns
139 
140## Metadata and SEO
141```tsx
142export async function generateMetadata({ params }): Promise<Metadata> {
143  const product = await getProduct(params.id);
144  return {
145    title: product.name,
146    description: product.description,
147    openGraph: { images: [product.image] },
148  };
149}
150```
151 
152## Middleware
153- Use `middleware.ts` at project root for auth checks, redirects, headers
154- Keep middleware lightweight — it runs on every matching request
155- Use `matcher` config to limit which routes trigger middleware
156 
157## Testing
158- Use `@testing-library/react` for component tests
159- Test Server Components by testing their rendered output
160- Test Server Actions as regular async functions
161- Use Playwright or Cypress for E2E testing of full page flows
162- Mock database calls in tests, not fetch calls
163 
164## Performance Guidelines
165- Use `next/image` for all images (automatic optimization)
166- Use `next/font` for font loading (no layout shift)
167- Use `next/link` for client-side navigation (prefetching)
168- Implement streaming with `loading.tsx` and `<Suspense>`
169- Use `dynamic()` imports for heavy client components
170- Prefer Server Components to reduce client JavaScript
171- Set appropriate `revalidate` values — don't over-fetch
172 
173## Common Pitfalls
174- Importing server-only code in Client Components (use `server-only` package)
175- Passing non-serializable props from Server to Client Components
176- Over-using `'use client'` — pushing it to the root layout
177- Not handling the `loading` and `error` states for each route segment
178- Forgetting to revalidate after mutations in Server Actions
179- Using `router.push()` in Server Actions instead of `redirect()`
180- Accessing `cookies()` or `headers()` in cached/static routes without declaring dynamic
181- Nesting `<Suspense>` boundaries inefficiently causing waterfall loading
182