Nextjs

# Next.js Best Practices for LLMs (2026)

_Last updated: January 2026 (aligned to Next.js 16.1.1)_

This document summarizes the latest, authoritative best practices for building, structuring, and maintaining Next.js applications. It is intended for use by LLMs and developers to ensure code quality, maintainability, and scalability.

---

1. Project Structure & Organization

- **Use the `app/` directory** (App Router) for all new projects. Prefer it over the legacy `pages/` directory.

- **Top-level folders:**

- `app/` — Routing, layouts, pages, and route handlers

- `public/` — Static assets (images, fonts, etc.)

- `lib/` — Shared utilities, API clients, and logic

- `components/` — Reusable UI components

- `contexts/` — React context providers

- `styles/` — Global and modular stylesheets

- `hooks/` — Custom React hooks

- `types/` — TypeScript type definitions

- **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. 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.

**Correct Approach:**

- If you need to use a Client Component (e.g., a component that uses hooks, browser APIs, or client-only libraries) inside a Server Component, you must:

1. Move all client-only logic/UI into a dedicated Client Component (with `'use client'` at the top).

2. Import and use that Client Component directly in the Server Component (no need for `next/dynamic`).

3. If you need to compose multiple client-only elements (e.g., a navbar with a profile dropdown), create a single Client Component that contains all of them.

**Example:**

// Server Component
import DashboardNavbar from "@/components/DashboardNavbar";

export default async function DashboardPage() {
  // ...server logic...
  return (
    <>
      <DashboardNavbar /> {/* This is a Client Component */}
      {/* ...rest of server-rendered page... */}
    </>
  );
}

**Why:**

- Server Components cannot use client-only features or dynamic imports with SSR disabled.

- Client Components can be rendered inside Server Components, but not the other way around.

**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)

- **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.

---

3. Component Best Practices

- **Component Types:**

- **Server Components** (default): For data fetching, heavy logic, and non-interactive UI.

- **Client Components:** Add `'use client'` at the top. Use for interactivity, state, or browser APIs.

- **When to Create a Component:**

- If a UI pattern is reused more than once.

- If a section of a page is complex or self-contained.

- If it improves readability or testability.

- **Naming Conventi