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

MistakeWhy it happensRule line that stops it
DB query inside a "use client" componentAgent 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 mutationHabit 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 pageFastest 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 leafEasier 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.