Skip to main content
Next.js 15 App RouterfrontendTarget: Next.js 15.1+ / React 19

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.

#nextjs cursorrules#nextjs 15 cursor rules#nextjs claude md#nextjs agent rules#nextjs system prompt for ai

Configuration Workbench

Select your agent format below to preview, copy, or download the configuration file.

Standard Cursor project configuration to guide autocomplete, composer, and inline edits.
30 lines•1.7 KB
# 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.

1Copy the `.cursorrules` file into the root directory of your Next.js project.
2If using Claude Code CLI, copy the `CLAUDE.md` configuration into your root folder.
3If using modern Cursor IDE (.mdc), save under `.cursor/rules/nextjs-15.mdc`.
4Restart your IDE or agent session to apply the instructions automatically.

Verified Agent Behavior Examples

Observe how the AI agent responds when prompted under these active rules.

Scenario: Scaffolding a dynamic route page in Next.js 15
User prompt: “Create a blog post page that reads the post slug from the URL parameters.”
Agent Behavior: The agent correctly writes an async Server Component that awaits `params` (`const { slug } = await params`), renders with `<Suspense>`, and fetches data on the server without adding `'use client'`.
Scenario: Handling form submission
User prompt: “Create a user newsletter signup form with validation.”
Agent Behavior: The agent creates a dedicated `actions/newsletter.ts` file with `'use server'`, validates email via Zod, and implements `useActionState` in a Client Component with pending states.

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`.