Next.js

Reference for Next.js 16+ App Router projects. Prefer the project's existing conventions, then steer with four leading words: boundary, dynamic by default, pass-through, and generated types.

The adoption, optimization, and development-loop references target Next.js 16.3+. Check their prerequisites before using them on a 16.x project; an upgrade is a separate change, not an implicit part of a runtime check. Prefer installed-version docs in node_modules/next/dist/docs/ (bundled since 16.2). Locate guides by filename because directory prefixes are numbered. For earlier versions, use the matching official upgrade or API documentation. Error pages under /docs/messages/ must be read online.

Branch-specific references, loaded on demand:

• boundary.md — server/client split, providers, server-only, where state and files go.
• caching.md — use cache, cacheLife, updateTag vs revalidateTag, and the traps that pass next build.
• actions-and-routes.md — Server Actions, Route Handlers, proxy.ts, metadata.
• typescript.md — PageProps/LayoutProps/RouteContext, typedRoutes, satisfies, discriminated unions.
• view-transitions.md — <ViewTransition>, canary-only.
• migration.md — what changed from 15, renames, removals.

First Checks

1. Locate next.config.{js,ts,mjs,cjs} and use its directory as the project root. Read cacheComponents, partialPrefetching, typedRoutes, and experimental.* flags. cacheComponents decides the caching branch.
2. Get the exact version from the lockfile. Major-version drift makes most of this skill's specifics wrong.
3. Locate the routing root (app/ or src/app/), proxy.ts, and whether the project still has a middleware.ts to migrate. If both app directories exist, app/ shadows src/app/; resolve the intended tree before migration.
4. Find existing data-fetching, auth, and error-handling conventions before introducing new ones.

Done when: the installed Next version is stated, the cacheComponents and partialPrefetching states are known, and the routing root is located.

Reach For The MCP Server

Next.js 16+ runs a built-in MCP endpoint at /_next/mcp inside the dev server; the next-devtools-mcp package connects an agent to it. It reports real build, runtime and type errors (get_errors), dev logs (get_logs), the route table (get_routes), a page's rendering info (get_page_metadata), and maps a Server Action ID back to its source (get_server_action_by_id). Discover the current surface with tools/list; tools and prerequisites vary by version. get_compilation_issues needs Turbopack.

Prefer it over guessing whenever a dev server is running: it answers from the running app rather than from this file. It is development-time only, and its tool list grows between releases.

Setup is .mcp.json at the project root:

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

If tools are missing: check Next 16+, confirm the dev server is running, and restart it if it was started before the config landed.

Choose The Workflow

Pick the requested branch; follow its prerequisite and verification pointers as needed. Complete its criterion before claiming the task done.

Adoption and runtime workflows

These references synthesize the four official vercel/next.js skills at commit 3cf1f7418ff9e3ce0f54b4c3212964e421933237. Each links its pinned source and the detailed recipes needed only on that branch.

Adding or changing a component

Apply boundary: layouts and pages are Server Components by default; "use client" marks an entry point, and every module it imports joins the client bundle. Push the directive down to the interactive leaf.

Apply pass-through to escape it: Server Components handed to a Client Component as children or props are not in its module graph — they render on the server and arrive as rendered output. This is what lets state live in a small client shell wrapped around server content.

Read boundary.md before adding a directive, a provider, or a piece of shared state.

Done when: each new "use client" sits at the smallest component that needs it, server-only modules reachable from the change import server-only, and props crossing the boundary are serializable — no functions, no class instances.

Fetching or caching data

Apply dynamic by default: make caching deliberate under cacheComponents. Read caching.md before changing a cached scope, lifetime, tag, or revalidation call; it owns request-data boundaries and existing-cache compatibility.

Done when: every cached scope's request-scoped inputs are read outside it and passed in as arguments, each use cache has a deliberate cacheLife profile or a stated reason to accept the default, and the invalidation verb matches the need — updateTag for read-your-writes, revalidateTag with a profile otherwise.

Writing a Server Action or Route Handler

Read actions-and-routes.md.

Done when: the action authenticates and authorizes internally, its result is a discriminated union rather than a thrown string, and dynamic APIs (params, cookies(), headers()) are awaited.

Typing routes and boundaries

Apply generated types: PageProps<'/route'>, LayoutProps<'/route'> and RouteContext<'/route'> are global, generated from the filesystem, and beat hand-written param types. Regenerate with next typegen.

Read typescript.md.

Done when: route components use the generated helpers rather than hand-written params types, and type checking passes — never silenced with typescript.ignoreBuildErrors.

Animating between states or routes

Read view-transitions.md first — the API is React canary, usable in the App Router only because Next bundles that channel.

Done when: the transition communicates a stated spatial relationship, it is triggered by startTransition, useDeferredValue or Suspense rather than a bare setState, and reduced motion is handled explicitly.

Upgrading from Next.js 15

Read migration.md.

Done when: middleware.ts is renamed to proxy.ts, every dynamic API is awaited, removed config is gone (experimental.ppr, experimental.dynamicIO, serverRuntimeConfig, AMP, next lint), and the image defaults that flipped are reviewed against the project's usage.

Project Structure

Next.js is deliberately unopinionated here and names three valid strategies. This skill standardizes on the third — split by feature or route:

• A feature owns its components, hooks and tests, colocated in its route segment. Colocation is safe: a segment is not routable until it holds a page.tsx or route.ts, and only what those return reaches the client.
• Shared code moves up to src/lib/ or src/components/ui/ only once a second feature needs it. components and lib carry no framework meaning.
• _folder (private) opts a folder out of routing — the practical reason is avoiding collisions with future Next.js file conventions.
• (folder) (route group) organizes by section, intent or team without touching the URL, and scopes a layout.tsx or loading.tsx to that group.

State follows the same logic: lift it to the closest common parent and no higher, where that parent is the smallest possible Client Component. See boundary.md for why height is expensive here specifically.

Review Checklist

• Every "use client" is at a leaf that needs it, not on a layout.
• Server Components reach client shells through children, not imports.
• Server-only modules import server-only; secrets never sit in a module a client file can reach.
• Cached scopes take request data as arguments; none reads cookies(), headers() or searchParams transitively.
• Server Actions authenticate; none trusts its caller.
• Dynamic APIs are awaited (params, searchParams, cookies(), headers()).
• Route components use PageProps / LayoutProps / RouteContext.
• Independent async work runs under Promise.all, and each await sits in the branch that uses it rather than at the top of the component.
• Suspense boundaries exist where streaming is worth it.
• The build passes with type checking on.
• Runtime changes follow dev-loop.md; navigation claims use the production-mode checks in their workflow, not the build alone.