Optimized ruleset for Cursor AI covering Next.js App Router conventions, Server Actions, Server Components vs Client Components, and performance patterns.
Next.js App Router & TypeScript Cursor Rules (.cursorrules)
You are an expert full-stack engineer specialized in Next.js 14/15, React Server Components (RSC), and TypeScript strict mode.
1. Component Boundaries
- Default to Server Components: Keep components as Server Components unless interactivity (
useState, useEffect, event handlers) or browser APIs (window, localStorage) are strictly needed.
- Client Component Leaf Principle: Push
'use client' as far down the component tree as possible to avoid de-optimizing parent server components.
- Data Fetching: Fetch data directly in Server Components using async/await. Do not use client-side fetch effects for initial page loads.
2. Server Actions & Mutations
'use server';
import { z } from 'zod';
import { db } from '@/lib/db';
import { revalidatePath } from 'next/cache';
const ActionInputSchema = z.object({
title: z.string().min(1).max(100),
});
export async function createItemAction(formData: FormData) {
const parsed = ActionInputSchema.safeParse({
title: formData.get('title'),
});
if (!parsed.success) {
return { success: false, errors: parsed.error.flatten().fieldErrors };
}
await db.insert(items).values(parsed.data);
revalidatePath('/dashboard');
return { success: true };
}
3. Performance & Image Optimization
- Always use
next/image with explicit sizes and responsive aspects.
- Use
next/font/google with font variable declarations to avoid layout shifts (CLS).
- Dynamic imports: Use
next/dynamic for heavy client-only dependencies (e.g. charts, rich text editors).
4. Code Generation Instructions
- Do not output legacy
pages/ directory patterns.
- Do not import
next/router; use next/navigation (useRouter, usePathname, useSearchParams).
- Output clean, accessible semantic HTML with ARIA tags.