RuleScan: pass
Next.js
Next.js App Router rule: Server Components by default, async request APIs, Server Actions with Zod validation, caching and revalidation, next/image and next/font.
Add a trust badge to your README
[](https://waxmark.app/items/nextjs/scan)
---
description: Next.js App Router conventions with TypeScript, Server Components, Server Actions, and Zod validation.
globs: "**/*.{ts,tsx}"
alwaysApply: false
---
# Next.js Best Practices
## Project Structure
- Use the App Router directory structure
- Place route-specific components next to the route in `app`
- Place shared components in `components` directory
- Place utilities and helpers in `lib` directory
- Use lowercase with dashes for directories (e.g., `components/auth-wizard`)
## Components
- Use Server Components by default
- Mark client components explicitly with `'use client'` and keep them at the leaves of the tree
- Wrap slow or data-dependent subtrees in `Suspense` with a fallback
- Use `next/dynamic` for heavy, non-critical client components
- Add `error.tsx` and `loading.tsx` per route segment instead of ad-hoc error boundaries
- Place static content and interfaces at file end
## Data Fetching
- Fetch data in Server Components with `async`/`await`; avoid `useEffect` for initial data
- In Next.js 15+, `params`, `searchParams`, `cookies()`, `headers()`, and `draftMode()` are async: `const { id } = await params`
- Fetches are uncached by default in Next.js 15+; opt in with `fetch(url, { next: { revalidate: 3600, tags: ['posts'] } })` or `'use cache'`
- Set route segment config (`export const dynamic`, `export const revalidate`) deliberately, not by copy-paste
- Use `revalidatePath` / `revalidateTag` after mutations instead of refetching on the client
## Server Actions
- Put mutations in Server Actions (`'use server'`) called from forms or `useActionState`
- Validate every action input with Zod on the server; never trust client-provided IDs or roles
- Return typed results (`{ ok: true, data } | { ok: false, errors }`) rather than throwing for expected failures
- Show pending state with `useFormStatus` or `useActionState`
## Performance
- Use `next/image` for images (explicit `width`/`height` or `fill`, `sizes` for responsive layouts, `priority` for LCP)
- Use `next/font` to self-host fonts and avoid layout shift
- Minimize `useEffect` and client state; favor Server Components where possible
- Keep third-party scripts out of the critical path with `next/script`
## Routing
- Use the App Router conventions (`page.tsx`, `layout.tsx`, `template.tsx`, `route.ts`)
- Implement loading and error states for routes
- Use dynamic routes appropriately and `generateStaticParams` for known paths
- Handle parallel and intercepting routes when needed
## Forms and Validation
- Use Zod schemas shared between client and server
- Validate on the server even when the client already validated
- Surface field errors from the action result
- Show loading states during form submission
## State Management
- Minimize client-side state
- Use React Context sparingly
- Prefer server state (URL, cookies, database) when possible
- Keep loading and empty states explicit