From 9b8c2bf0ca352e24cdd7f8263dbef690e34c9f07 Mon Sep 17 00:00:00 2001 From: travish Date: Wed, 4 Mar 2026 13:20:48 -0600 Subject: [PATCH] docs: update nextjs.instructions.md structure and formatting; fix typos --- instructions/nextjs.instructions.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/instructions/nextjs.instructions.md b/instructions/nextjs.instructions.md index 300dd58d7..cc23983ab 100644 --- a/instructions/nextjs.instructions.md +++ b/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,7 +67,7 @@ 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. @@ -74,7 +75,7 @@ Always move client-only UI into a Client Component and import it directly in you --- -## 2. Component Best Practices +## 3. Component Best Practices - **Component Types:** - **Server Components** (default): For data fetching, heavy logic, and non-interactive UI. @@ -101,7 +102,7 @@ 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 @@ -109,7 +110,7 @@ Always move client-only UI into a Client Component and import it directly in you - **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.