# Cursor Rules for Next.js App Router Projects

> A short, glob-scoped .cursor/rules file for App Router repos: server/client boundary, Server Actions, Suspense, and the parts that belong in a skill instead.

Canonical: https://www.agentickit.co/compare/cursor-rules-nextjs-app-router
Last updated: 2026-11-18

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](https://www.agentickit.co/compare/cursor-rules-vs-skills)). 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](https://www.agentickit.co/skills/next-app-router).

## 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 `&lt;Suspense&gt;` 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](https://www.agentickit.co/tools/rules-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
<table><thead><tr><th>Mistake</th><th>Why it happens</th><th>Rule line that stops it</th></tr></thead><tbody><tr><td>DB query inside a "use client" component</td><td>Agent copies a pattern from a Server Component without checking the directive at the top of the file it's editing</td><td>"Never import server-only modules into a file marked use client"</td></tr><tr><td>Client-side fetch to your own route handler for a mutation</td><td>Habit carried over from the Pages Router / plain REST backends</td><td>"Mutations go through Server Actions, not client-side fetch"</td></tr><tr><td>One giant Suspense boundary wrapping the whole page</td><td>Fastest way to silence a loading-state warning</td><td>"Wrap slow data fetches in their own Suspense boundary"</td></tr><tr><td>"use client" added to a parent layout instead of the one interactive leaf</td><td>Easier than tracing which child actually needs state</td><td>"Default to Server Components. Add use client only on the leaf"</td></tr></tbody></table>

## 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](https://www.agentickit.co/skills/next-app-router), which the [react-specialist agent](https://www.agentickit.co/agents/react-specialist) and the `/build-page` command both load automatically.



## FAQ

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

## Related
- [Next.js App Router & Server Components skill](https://www.agentickit.co/skills/next-app-router)
- [Cursor Rules vs Skills vs Commands](https://www.agentickit.co/compare/cursor-rules-vs-skills)
- [Cursor Rules Examples: React Native, Go, Flutter, Svelte](https://www.agentickit.co/compare/cursor-rules-examples-react-native-go-flutter-svelte)
- [Rules File Grader](https://www.agentickit.co/tools/rules-grader)
- [Cursor rules for SaaS founders](https://www.agentickit.co/blog/cursor-rules-saas-founders)
- [react-specialist agent](https://www.agentickit.co/agents/react-specialist)
