Opinionated, modern Next.js ruleset — optimized for App Router, server-first rendering, and scalable project architecture.

next-ide-context-modern-rules.mdc

---
description: Opinionated, modern Next.js ruleset — optimized for App Router, server-first rendering, and scalable project architecture.
globs: ["app/**", "pages/**", "*.ts", "*.tsx"]
alwaysApply: false
---

# 🧠 Next.js Modern Practices

## 🗂 Routing
- Use App Router (`app/`) — Pages Router is legacy.
- Use folders as routes: `app/dashboard/page.tsx` → `/dashboard`.
- Group routes with `()` to avoid affecting the URL: `(auth)/login/page.tsx`.
- Use `layout.tsx`, `loading.tsx`, and `error.tsx` for UX structure.

## 🔁 Server vs Client
- Default to **Server Components** — lean, fast, SEO-friendly.
- Add `'use client'` only when needed (interactivity, hooks).
- Keep Client Components isolated; colocate UI logic.

## ⚙️ Data Fetching
- Use native `fetch()` in Server Components — no `axios`.
- Cache by default (`force-cache`); opt-out via `{ cache: 'no-store' }`.
- Use `generateStaticParams` and `revalidate` for ISR.

## 🧱 Layouts
- Use nested `layout.tsx` to compose UI shells.
- Share state via Server Components when possible.
- Avoid deep layout chains unless necessary.

## 🌐 Metadata
- Use `export const metadata` for SEO, OpenGraph, Twitter cards.
- Use dynamic `generateMetadata()` for per-page metadata.
- Add `robots.txt` and `sitemap.xml` via `next-sitemap`.

## 🎨 Styling
- Tailwind CSS recommended.
- Use `@apply` and `@layer` to create design systems.
- Co-locate styles when using CSS Modules.
- Avoid runtime inline styles.

## 🧬 State
- Prefer local state via `useState`, `useReducer`.
- Use `useContext` or Zustand/Jotai only when necessary.
- Don’t sync server state to client unless required.

## 📦 File Structure
- app/
- (group)/page.tsx # route
- (group)/layout.tsx # layout
- components/
- ui/ # styled UI elements
- core/ # business-logic components
- lib/
- fetchers.ts # server utilities
- auth.ts # auth logic

## 📈 Performance
- Use `next/image` + `fill` or `sizes` for responsiveness.
- Code-split with `next/dynamic()` where hydration matters.
- Avoid unnecessary Client Components.

## 🛡 Security
- Use middleware for auth / redirects.
- Sanitize all external input.
- Configure secure headers (CSP, Referrer-Policy, etc).

## 🧪 Testing
- Use Vitest/Jest for units, Playwright for E2E.
- Test behavior, not implementation.
- Use CI (e.g., GitHub Actions) to run on PRs.

## ♿ Accessibility
- Use semantic HTML.
- Validate with `eslint-plugin-jsx-a11y`.
- Test keyboard nav + screen reader flow.