Home › Next.js › Next.js App Router (TypeScript) rules

Next.js App Router (TypeScript) rules

Cursor project rules for Next.js 15 App Router apps with TypeScript, Server Components, and Tailwind.

CursorNext.js

How to use

Save this as .cursor/rules/nextjs.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

---
description: Next.js App Router conventions
globs: ["app/**/*.{ts,tsx}", "components/**/*.tsx", "lib/**/*.ts"]
alwaysApply: false
---

# Next.js App Router

## Architecture
- Default to React Server Components. Add `"use client"` only for state, effects, browser APIs, or event handlers, and push it to the smallest leaf component.
- Fetch data in Server Components or route handlers, never in `useEffect` for initial page data.
- Mutations go through Server Actions in `app/**/actions.ts` with `"use server"`; validate every input with zod.
- Keep secrets in server-only modules; import `server-only` at the top of `lib/server/*`.

## Files and routing
- One route segment per folder: `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx`.
- Export `generateMetadata` (or `metadata`) from every public page.
- Use `next/image` for images and `next/link` for internal links.

## TypeScript
- `strict: true`. No `any`; use `unknown` and narrow.
- Type props inline with `type Props = {...}`; avoid `React.FC`.

## Styling
- Tailwind utility classes; extract a component, not a custom CSS class, when markup repeats.

## Before finishing
- Run `pnpm lint && pnpm typecheck && pnpm build`. Fix every error; do not silence with `// @ts-ignore`.