Cursor Rules for Next.js App Router Projects
An App Router rules file should be short and glob-scoped to app/**, enforcing the server/client boundary, Server Action conventions and Suspense usage. Full architecture guidance — streaming patterns, parallel routes, Core Web Vitals tradeoffs — belongs in a skill the agent loads on demand, not in a rule that fires on every turn. Last updated 2026-10-26 by Rakshit Yadav.
What goes in the rule vs. the skill
A rule is a standing constraint Cursor loads on every matching file; a skill is a longer playbook the agent opens when a task calls for it (see Rules vs Skills vs Commands). For App Router, that split matters because the full set of conventions — streaming SSR, parallel routes, when to reach for loading.tsx vs a manual Suspense boundary — is too long to keep in context on every single turn. Put the three or four hard bans in a glob-scoped rule, and move the "how and why" into the next-app-router skill.
A working .cursor/rules/app-router.mdc
Scope it to app/** so it never loads for API routes, scripts or config files:
---
description: Next.js App Router conventions
globs: app/**/*.tsx,app/**/*.ts
alwaysApply: false
---
- Never import server-only modules (db client, API secrets, Node `fs`) into a file
marked "use client". If a client component needs that data, fetch it in a
parent Server Component and pass it down as a prop.
- Mutations go through Server Actions, not client-side fetch to a route handler,
unless the caller is outside Next.js (webhook, external service).
- Wrap slow data fetches in their own `<Suspense>` boundary with a purpose-built
fallback. Do not wrap the whole page in one Suspense boundary at the root.
- Default to Server Components. Add "use client" only on the leaf that needs
state, effects or a browser API, not on its parent.Four lines, each one checkable by reading a diff. That is what keeps a rule file useful instead of ignored — see the grading criteria on the Rules File Grader.
Why a rule instead of relying on the model's defaults
Current models default to the client/server split reasonably often, but they slip under two conditions: a large existing file that is already "use client" at the top (so new server-only code gets added inside it without a second thought), and a Server Action that quietly calls fetch to an internal API route instead of doing the work directly. Both are easy to miss in review and easy to catch with a one-line rule, which is why they are the ones worth encoding rather than the full architecture writeup.
Common mistakes this rule catches
| Mistake | Why it happens | Rule line that stops it |
|---|---|---|
| DB query inside a "use client" component | Agent copies a pattern from a Server Component without checking the directive at the top of the file it's editing | "Never import server-only modules into a file marked use client" |
| Client-side fetch to your own route handler for a mutation | Habit carried over from the Pages Router / plain REST backends | "Mutations go through Server Actions, not client-side fetch" |
| One giant Suspense boundary wrapping the whole page | Fastest way to silence a loading-state warning | "Wrap slow data fetches in their own Suspense boundary" |
| "use client" added to a parent layout instead of the one interactive leaf | Easier than tracing which child actually needs state | "Default to Server Components. Add use client only on the leaf" |
What stays out of the rule
Leave these in the skill, not the rule: parallel and intercepting route layout, streaming strategy for slow third-party APIs, Core Web Vitals tradeoffs between static and dynamic rendering, and anything that needs an example rather than a one-line ban. A rule the agent reads on every file should stay small enough that you could recite it; everything else goes in the App Router skill, which the react-specialist agent and the /build-page command both load automatically.
Related pages
Frequently asked questions
Should App Router conventions be a rule or a skill?
Both, split by size. The three or four non-negotiable bans (server/client boundary, Server Actions for mutations, scoped Suspense) go in a short glob-scoped rule. The full reasoning and longer patterns go in a skill the agent loads when the task matches.What glob should an App Router rule use?
Scope it to app/**/*.tsx and app/**/*.ts so it only loads for files inside the App Router tree, not for API routes, scripts, or config.Does a Cursor rule actually prevent 'use client' misuse?
It catches most of it. A short, specific rule that names the exact failure (importing a server-only module into a client component) is far more effective than a vague 'follow Next.js best practices' line, because the agent can check it against the diff it just wrote.Where do I get the fuller App Router guidance?
The next-app-router skill in AgenticKit covers nested layouts, streaming SSR, parallel routes and Server Action patterns in more depth than a rule file should carry.
Get the Next.js App Router skill
AgenticKit ships a full next-app-router skill plus a react-specialist agent that already knows these conventions. Install both in one command.