Cursor Rules for Next.js App Router
Stop Cursor from treating your App Router project like Pages Router. Here is a complete .cursor/rules setup that enforces server components, route groups, and colocated patterns.
Why Next.js App Router needs its own rules
The App Router introduced a fundamentally different mental model: components are Server Components by default, layouts are nested, and data fetching happens at the component level -not in getServerSideProps. Without explicit rules, Cursor defaults to the Pages Router patterns it has seen most often in training data. That means it will add "use client" unnecessarily, reach for useEffect to fetch data, and put everything in pages/ instead of app/.
The .cursor/rules directory format
Cursor moved away from a single .cursorrules file to a .cursor/rules/ directory of .mdc files. Each .mdc file can be scoped: always-applied, auto-attached to matching file globs, or agent-requested on demand. For a Next.js project, split your rules by concern -one file for routing, one for components, one for data fetching. This keeps context tight and prevents token waste.
Ready-to-use template
Place this at .cursor/rules/nextjs.mdc. It enforces App Router conventions, server-first architecture, and file naming.
---
description: Next.js App Router conventions for this project
globs: ["**/*.tsx", "**/*.ts", "**/app/**"]
alwaysApply: true
---
# Next.js App Router Rules
## Architecture
- Default to Server Components. Add "use client" ONLY when you need browser APIs, event handlers, or React hooks.
- Never use useEffect to fetch data. Use async Server Components and Next.js fetch() with caching options.
- Route handlers go in app/api/[route]/route.ts -one file per HTTP method group.
## Folder Structure
- app/ -routes only. Pages should be thin; import from features/ or components/.
- src/components/ -shared UI components used across 2+ routes.
- src/lib/ -server-only utilities, Prisma client, auth helpers. Add import 'server-only' at top.
- src/hooks/ -client-side custom hooks (use* prefix). All files need "use client" context.
## Routing
- Use route groups (marketing), (dashboard) for layouts without URL segments.
- Prefix private non-routable folders with _ (e.g., _components next to a route).
- loading.tsx and error.tsx must exist for every route segment with async data.
## TypeScript
- All props typed with interfaces. No implicit any.
- Use React.FC sparingly -prefer function declarations.
- Infer Zod schema types with z.infer<typeof Schema> -do not duplicate types.
## Naming
- Files: kebab-case (user-profile.tsx). Exports: PascalCase (UserProfile).
- Page files are always page.tsx. Layout files are always layout.tsx.
- API route files are always route.ts.Scoping rules to file patterns
Use the globs field in the frontmatter to auto-attach this rule whenever Cursor opens a matching file. For example, setting globs: ["**/app/**/*.tsx"] means the rule only fires for files inside the app/ directory -your React utility components in src/components/ won't get the routing-specific instructions.
What to do next
After dropping this file in, test it: ask Cursor to create a new page with a data-fetching pattern and verify it generates an async Server Component -not a useEffect. If it still defaults to useEffect, add a negative example to your rules file ("Never do: useEffect(() => { fetch(...) }, [])").