Cursor Rules for Next.js: The 2025 Guide That Actually Works (With Copy-Paste Templates)

'use client';
export default function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState(null);
  useEffect(() => {
    fetch(`/api/users/${userId}`).then(res => res.json()).then(setUser);
  }, [userId]);
  return <div>{user?.name}</div>;
}

// Server Component - fetches on server, no loading state needed
async function UserProfile({ userId }: { userId: string }) {
  const user = await db.users.findUnique({ where: { id: userId } });
  return <div>{user.name}</div>;
}

// Unnecessary API route + client-side form
export async function POST(request: Request) {
  const body = await request.json();
  await db.users.update({ where: { id: body.id }, data: body });
  return Response.json({ success: true });
}

// Server Action - simpler, progressively enhanced
'use server';
export async function updateUser(formData: FormData) {
  const name = formData.get('name') as string;
  await db.users.update({ where: { id: '1' }, data: { name } });
  revalidatePath('/users');
}

app/users/UserList.tsx        ❌ Won't be routable
app/users/UserDetail.tsx      ❌ Wrong location

app/users/page.tsx            ✅ Route component
app/users/loading.tsx         ✅ Loading UI
app/users/_components/        ✅ Private folder
  UserList.tsx                ✅ Reusable component

<img src="/hero.jpg" alt="Hero" />
<a href="/about">About</a>

import Image from 'next/image';
import Link from 'next/link';

<Image src="/hero.jpg" alt="Hero" width={800} height={600} />
<Link href="/about">About</Link>

your-project/
  .cursor/
    rules/
      nextjs-core.mdc
      server-components.mdc
      client-components.mdc

---
description: Core Next.js App Router principles
globs: ["app/**/*.tsx", "app/**/*.ts"]
alwaysApply: true
---

# Next.js App Router Core Rules

## Mental Model
- Server Components by DEFAULT (no 'use client' needed)
- Add 'use client' ONLY for interactivity/hooks
- Use Server Actions for mutations (not API routes)
- Fetch data directly in Server Components

## File Conventions
- page.tsx = route component
- layout.tsx = shared layout
- loading.tsx = loading UI with Suspense
- error.tsx = error boundary
- _folder/ = private components (not routable)
- actions.ts = Server Actions

## Before Writing Code
1. Can this be a Server Component? (default: YES)
2. Do I need hooks/events? (if NO → Server Component)
3. Should this be a Server Action vs API route?
4. Am I following Next.js file structure?

## Critical Rules
- Check existing code with codebase_search first
- NEVER add 'use client' unless absolutely necessary
- Use async Server Components for data fetching
- Forms should work without JavaScript when possible

---
description: Server Component patterns
globs: ["app/**/page.tsx", "app/**/layout.tsx"]
alwaysApply: false
---

# Server Components

## Pattern: Async Data Fetching
```typescript
async function ProductPage({ params }: { params: { id: string } }) {
  const product = await db.products.findUnique({ 
    where: { id: params.id } 
  });
  return {product.name};
}
```

## NEVER in Server Components
❌ NO useState, useEffect, or any hooks
❌ NO event handlers (onClick, onChange)
❌ NO browser APIs (window, document)
❌ NO 'use client' directive

## Composition
Server Components can render Client Components:
```typescript
import { InteractiveButton } from './_components/InteractiveButton';

async function Page() {
  const data = await fetchData();
  return (
    
      {data.title}
       {/* Client Component */}
    
  );
}
```

## Streaming with Suspense
```typescript
import { Suspense } from 'react';

export default function Page() {
  return (
    }>
      
    
  );
}
```

---
description: Client Component patterns for interactivity
globs: ["app/**/_components/*.tsx"]
alwaysApply: false
---

# Client Components

## When to Add 'use client'
ONLY when you need:
- Hooks (useState, useEffect, useContext)
- Event handlers (onClick, onChange, onSubmit)
- Browser APIs (window, localStorage)
- Third-party libraries using hooks

## Pattern: Minimal Client Component
```typescript
'use client'; // Required at TOP of file

import { useState } from 'react';

export function Counter() {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    
  );
}
```

## Push 'use client' Down the Tree
Keep it at the leaf level:
```typescript
// ✅ GOOD: Only Counter is client-side
export default function Page() { // Server Component
  return (
    
       {/* Server */}
       {/* Client */}
       {/* Server */}
    
  );
}
```

## Client Data Fetching (when necessary)
```typescript
'use client';
import { useState, useEffect } from 'react';

export function ClientData() {
  const [data, setData] = useState(null);
  
  useEffect(() => {
    fetch('/api/data')
      .then(res => res.json())
      .then(setData);
  }, []);
  
  return {data?.content};
}
```

But prefer Server Components with Suspense instead.

---
description: Server Actions for mutations
globs: ["app/**/actions.ts"]
alwaysApply: false
---

# Server Actions

## Pattern: Form with Server Action
```typescript
// actions.ts
'use server';

import { revalidatePath } from 'next/cache';

export async function createProduct(formData: FormData) {
  const name = formData.get('name') as string;
  
  // Validation
  if (!name) return { error: 'Name required' };
  
  // Mutation
  await db.products.create({ data: { name } });
  
  // Revalidate cache
  revalidatePath('/products');
  
  return { success: true };
}

// page.tsx
import { createProduct } from './actions';

export default function NewProduct() {
  return (
    
      
      Create
    
  );
}
```

## When to Use
✅ Form submissions
✅ Data mutations (create/update/delete)
✅ Progressive enhancement needed

## When NOT to Use
❌ Data fetching (use Server Components)
❌ GET requests (use Route Handlers)
❌ Webhooks (use Route Handlers)

---
description: API Route Handlers
globs: ["app/api/**/route.ts"]
alwaysApply: false
---

# Route Handlers

## Pattern: RESTful API
```typescript
// app/api/users/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  const users = await db.users.findMany();
  return NextResponse.json(users);
}

export async function POST(request: Request) {
  const body = await request.json();
  const user = await db.users.create({ data: body });
  return NextResponse.json(user, { status: 201 });
}

// app/api/users/[id]/route.ts
export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const user = await db.users.findUnique({ 
    where: { id: params.id } 
  });
  return NextResponse.json(user);
}
```

## When to Use
✅ External API integrations
✅ Webhooks
✅ OAuth callbacks
✅ Non-HTML responses

## When NOT to Use
❌ Simple form submissions (use Server Actions)