Next.js 15 App Router AI Agent Rules & Cursorrules
Enforce Next.js 15 App Router conventions and Server Actions in Cursor, Claude Code, and Copilot.
Prevent AI coding agents from generating obsolete Next.js Pages router code, leaking sensitive server logic into client bundles, or misusing React 19 hooks.
Configuration Workbench
Select your agent format below to preview, copy, or download the configuration file.
# Next.js 15 & React 19 Cursor Rules
You are an expert Next.js 15, React 19, TypeScript, and Tailwind CSS developer.
## Core Architecture
- Framework: Next.js 15 App Router (NOT Pages router).
- Language: TypeScript with strict mode enabled. Never use 'any'.
- React: React 19. Utilize React 19 Compiler idioms (avoid unnecessary useMemo/useCallback).
- Styling: Tailwind CSS with mobile-first responsive utility classes.
- Icons: Lucide React.
- Validation: Zod for runtime schema validation.
## Next.js 15 Specifics
- Async request headers: In Next.js 15, 'cookies()', 'headers()', 'params', and 'searchParams' are Promises. ALWAYS await them.
Example: const { id } = await params; const cookieStore = await cookies();
- Server Components by default: Keep all data-fetching and database queries on the server.
- Add 'use client' ONLY to components requiring browser events, React state, or browser APIs.
- Keep Client Components small and leaf-level. Pass server-fetched data as props.
## Data Mutations & Server Actions
- Co-locate Server Actions in 'actions.ts' files marked with 'use server' at the top.
- ALWAYS validate Server Action arguments using Zod schemas with 'safeParse'.
- Return structured Result objects: { success: true, data: T } | { success: false, error: string }.
- Never throw unchecked errors from Server Actions to the client.
- Call 'revalidatePath' or 'revalidateTag' after successful mutations.
## Performance & Accessibility
- Wrap asynchronous Server Components in '<Suspense fallback={<Skeleton />}>'.
- Use 'next/image' with explicit width, height, or fill + sizes.
- Ensure all interactive elements have semantic HTML and accessible ARIA attributes.Pro-tip: Place this file directly in the root directory of your Next.js 15 App Router project. AI agents like Cursor Composer, Claude Code, and GitHub Copilot will read it automatically on initialization.
Architectural Principles Enforced
When this configuration file is loaded into Cursor or Claude Code, the agent strictly enforces the following design invariants:
All page and layout components are Server Components by default; never add 'use client' without interactive state.
Always await asynchronous runtime functions: `await params`, `await searchParams`, `await cookies()`, `await headers()`.
Execute database mutations exclusively through dedicated Server Actions in separate `actions.ts` files with 'use server'.
Enforce runtime data validation on all Server Action inputs using Zod `safeParse`.
Use Suspense boundaries with skeleton fallbacks for all asynchronous data-fetching components.
Never import server-only packages (Prisma, database drivers, secrets) into Client Components.
Installation & Repository Setup
Place in project root as `.cursorrules` or `.cursor/rules/nextjs.mdc`, or save as `CLAUDE.md` for Anthropic Claude Code CLI.
Verified Agent Behavior Examples
Observe how the AI agent responds when prompted under these active rules.
Frequently Asked Questions
Why do AI agents keep forgetting to await params in Next.js 15?
Because most LLM training data is dominated by Next.js 13 and 14 where params was a synchronous object. Next.js 15 made params an asynchronous Promise. Adding this .cursorrules file forces the agent to await params every time.
Where should I save the .cursorrules file in my repository?
Place it in the root directory of your project named `.cursorrules`. If you use modern Cursor rules, you can also place it under `.cursor/rules/nextjs.mdc`.