Format and Structure nextjs.instructions.md

instructions/nextjs.instructions.md

@@ -1,6 +1,6 @@
 ---
 description: "Best practices for building Next.js (App Router) apps with modern caching, tooling, and server/client boundaries (aligned with Next.js 16.1.1)."
-applyTo: '**/*.tsx, **/*.ts, **/*.jsx, **/*.js, **/*.css'
+applyTo: "**/*.tsx, **/*.ts, **/*.jsx, **/*.js, **/*.css"
 ---
 
 # Next.js Best Practices for LLMs (2026)
@@ -26,11 +26,12 @@ This document summarizes the latest, authoritative best practices for building,
 - **Colocation:** Place files (components, styles, tests) near where they are used, but avoid deeply nested structures.
 - **Route Groups:** Use parentheses (e.g., `(admin)`) to group routes without affecting the URL path.
 - **Private Folders:** Prefix with `_` (e.g., `_internal`) to opt out of routing and signal implementation details.
-
 - **Feature Folders:** For large apps, group by feature (e.g., `app/dashboard/`, `app/auth/`).
 - **Use `src/`** (optional): Place all source code in `src/` to separate from config files.
 
-## 2.1. Server and Client Component Integration (App Router)
+## 2. Next.js 16+ App Router Best Practices
+
+### 2.1. Server and Client Component Integration (App Router)
 
 **Never use `next/dynamic` with `{ ssr: false }` inside a Server Component.** This is not supported and will cause a build/runtime error.
 
@@ -66,15 +67,15 @@ export default async function DashboardPage() {
 **Summary:**
 Always move client-only UI into a Client Component and import it directly in your Server Component. Never use `next/dynamic` with `{ ssr: false }` in a Server Component.
 
-## 2.2. Next.js 16+ async request APIs (App Router)
+### 2.2. Next.js 16+ async request APIs (App Router)
 
 - **Assume request-bound data is async in Server Components and Route Handlers.** In Next.js 16, APIs like `cookies()`, `headers()`, and `draftMode()` are async in the App Router.
 - **Be careful with route props:** `params` / `searchParams` may be Promises in Server Components. Prefer `await`ing them instead of treating them as plain objects.
 - **Avoid dynamic rendering by accident:** Accessing request data (cookies/headers/searchParams) opts the route into dynamic behavior. Read them intentionally and isolate dynamic parts behind `Suspense` boundaries when appropriate.
 
 ---
 
-## 2. Component Best Practices
+## 3. Component Best Practices
 
 - **Component Types:**
   - **Server Components** (default): For data fetching, heavy logic, and non-interactive UI.
@@ -101,15 +102,15 @@ Always move client-only UI into a Client Component and import it directly in you
 - **Testing:**
   - Co-locate tests with components (e.g., `UserCard.test.tsx`).
 
-## 3. Naming Conventions (General)
+## 4. Naming Conventions (General)
 
 - **Folders:** `kebab-case` (e.g., `user-profile/`)
 - **Files:** `PascalCase` for components, `camelCase` for utilities/hooks, `kebab-case` for static assets
 - **Variables/Functions:** `camelCase`
 - **Types/Interfaces:** `PascalCase`
 - **Constants:** `UPPER_SNAKE_CASE`
 
-## 4. API Routes (Route Handlers)
+## 5. API Routes (Route Handlers)
 
 - **Prefer API Routes over Edge Functions** unless you need ultra-low latency or geographic distribution.
 - **Location:** Place API routes in `app/api/` (e.g., `app/api/users/route.ts`).
@@ -124,7 +125,7 @@ Always move client-only UI into a Client Component and import it directly in you
 
 - **Do not call your own Route Handlers from Server Components** (e.g., `fetch('/api/...')`) just to reuse logic. Prefer extracting shared logic into modules (e.g., `lib/`) and calling it directly to avoid extra server hops.
 
-## 5. General Best Practices
+## 6. General Best Practices
 
 - **TypeScript:** Use TypeScript for all code. Enable `strict` mode in `tsconfig.json`.
 - **ESLint & Prettier:** Enforce code style and linting. Use the official Next.js ESLint config. In Next.js 16, prefer running ESLint via the ESLint CLI (not `next lint`).
@@ -148,7 +149,7 @@ Always move client-only UI into a Client Component and import it directly in you
   - Write clear README and code comments.
   - Document public APIs and components.
 
-## 6. Caching & Revalidation (Next.js 16 Cache Components)
+## 7. Caching & Revalidation (Next.js 16 Cache Components)
 
 - **Prefer Cache Components for memoization/caching** in the App Router.
   - Enable in `next.config.*` via `cacheComponents: true`.
@@ -162,18 +163,18 @@ Always move client-only UI into a Client Component and import it directly in you
   - Use `updateTag(...)` inside **Server Actions** when you need “read-your-writes” / immediate consistency.
 - **Avoid `unstable_cache`** for new code; treat it as legacy and migrate toward Cache Components.
 
-## 7. Tooling updates (Next.js 16)
+## 8. Tooling updates (Next.js 16)
 
 - **Turbopack is the default dev bundler.** Configure via the top-level `turbopack` field in `next.config.*` (do not use the removed `experimental.turbo`).
 - **Typed routes are stable** via `typedRoutes` (TypeScript required).
 
-# Avoid Unnecessary Example Files
+## 9. Avoid Unnecessary Example Files
 
 Do not create example/demo files (like ModalExample.tsx) in the main codebase unless the user specifically requests a live example, Storybook story, or explicit documentation component. Keep the repository clean and production-focused by default.
 
-# Always use the latest documentation and guides
+## 10. Always Use the Latest Documentation and Guides
 
-- For every nextjs related request, begin by searching for the most current nextjs documentation, guides, and examples.
+- For every Next.js related request, begin by searching for the most up-to-date Next.js documentation, guides, and examples.
 - Use the following tools to fetch and search documentation if they are available:
   - `resolve_library_id` to resolve the package/library name in the docs.
-  - `get_library_docs` for up to date documentation.
+  - `get_library_docs` for up-to-date documentation.