Skip to main content
skill CX Codex

next-best-practices · laguagu — Claude Code skill: features and setup

The next-best-practices Claude Code skill applies Next.js App Router practices while writing or reviewing code. It covers hydration bugs, RSC boundaries, async APIs, and data handling.

MIT 286 installs ★ 74 updated 2026-11-14

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add laguagu/claude-code-nextjs-skills --skill next-best-practices -a claude-code
Open on GitHub

What next-best-practices does

The skill guides changes to Next.js App Router code, from file conventions and route handlers to metadata and data access. It covers Server and Client Component boundaries, image and font handling, and bundling. For the affected area, it reads the documentation that matches the project's installed Next.js version and checks the project configuration.

Before other work, it compares the installed version with Next.js security advisories. For upgrades, it accounts for API changes and suggests relevant codemods; it keeps the existing router, caching mode, and package manager unless migration is requested. The installed Next.js version determines which APIs and security fixes apply.

After changes, it recommends the project's lint and typecheck scripts, a production build, and exercising the changed route with next start. A development render can miss prerendering and Suspense issues.

What it helps with

  • track down hydration errors
  • review Server and Client Component boundaries
  • update code for asynchronous route parameters
  • identify breaking changes after a Next.js upgrade
  • inspect route handlers and caching behavior

Example prompts for the agent

  • Review this Next.js route for hydration bugs and RSC boundary violations.
  • Update the blog page to match the Next.js version installed in this project.
  • Investigate the build errors after the Next.js upgrade and suggest a suitable codemod.

How to install next-best-practices

1Skills CLI (Vercel)

npx skills add laguagu/claude-code-nextjs-skills --skill next-best-practices -a claude-code

2Manually: put the files in place

~/.claude/skills/next-best-practices/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/next-best-practices/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about next-best-practices

How do I install next-best-practices in Claude Code?

Run npx skills add laguagu/claude-code-nextjs-skills --skill next-best-practices -a claude-code. The skill file is at ~/.claude/skills/next-best-practices/SKILL.md.

What does next-best-practices do?

It helps write and review Next.js App Router code, including hydration, RSC boundaries, async APIs, and data patterns. It consults documentation for the installed Next.js version.

How does Next.js 16 handle route parameters?

In Next.js 16, params, searchParams, cookies(), and headers() return promises. The skill accounts for that change when reviewing or editing code.

Source text

SKILL.md · MIT
---
name: next-best-practices
description: Next.js App Router best practices covering file conventions, RSC boundaries, async APIs, data patterns, hydration errors, metadata, route handlers, image/font optimization, and bundling. Use when writing or reviewing Next.js code to prevent hydration errors, RSC violations, data waterfalls, and configuration mistakes.
---

# Next.js review and implementation

Read the installed `next` version and relevant `node_modules/next/dist/docs/`
pages before changing framework behavior. Those docs and project configuration
take precedence; use a matching online version/source tag when local docs are
unavailable. Next.js publishes workflow skills in vercel/next.js `skills/`.

Docs are bundled from 16.2; in a monorepo, read the app's own `next` package.
The nextjs.org links in these files have local equivalents with numbered
folders, so search by file name (`find node_modules/next/dist/docs -name proxy.md`).
`01-app/02-guides/upgrading/version-16.md` lists the breaking changes.
Per-error pages (`/docs/messages/*`) are only online; the dev/build output
carries the error's fix options.
Exact exports are also in `node_modules/next/{server,navigation,headers,cache}.d.ts`.

Before other work, compare the installed version with Next.js security
advisories and tell the user when it is affected. As of 2026-11-09 the patched
releases are 16.4.5 and 15.5.29. 16.0.0–16.4.0 and 15.x up to 15.5.27 have
critical RCEs: `use cache` functions returning typed arrays
(GHSA-673q-mjm6-r5xr, 16.x only, no workaround) and self-hosted image
optimization of SVGs on glibc Linux (GHSA-2464-fhr4-w9xw; interim fix: sharp
0.35.5+), plus a Server Actions DoS (GHSA-p3m5-59mp-jv5r); 16.4.1 and 15.5.28
fixed those. Seven medium advisories of 2026-11-03 remain through 16.4.4 and
15.5.28: cross-user `use cache` disclosure (GHSA-rhh4-g77r-r9qj and three more,
16.x only), cross-client response injection when self-hosted
(GHSA-pc58-hwjq-p385), an image-optimization SVG bypass and an Edge-route
cookie exposure. From 16.4,
`experimental.agentUpgrade` (default `'security'`) reminds during
`next dev`/`next build`; 16.3.x and older get no reminder.

## Next.js 16 changes older examples miss

- Sync request access is removed: `cookies()`, `headers()`, `draftMode()`,
  `params` (including image-metadata routes), `searchParams` and sitemap `id`
  are promises. `next typegen` generates global `PageProps<'/route'>`,
  `LayoutProps` and `RouteContext` types.
- `middleware.ts` is deprecated: `proxy.ts` exporting `proxy` (or default)
  runs on Node.js only and rejects a `runtime` option; code that needs Edge
  stays in `middleware.ts`. Codemod: `npx @next/codemod@latest middleware-to-proxy .`.
- Turbopack is the default for `dev` and `build`; a custom `webpack` config
  fails the build unless `--webpack` keeps it or explicit `--turbopack` ignores
  it. `next lint` is removed and
  `next build` no longer lints. `serverRuntimeConfig`/`publicRuntimeConfig`
  are removed.
- Every parallel-route slot needs `default.tsx`, or the build fails.
- `next/image`: `priority` is deprecated for `preload`; `qualities` defaults to
  `[75]` (other `quality` values are coerced); local `src` with a query string
  needs `images.localPatterns`; `images.domains` is deprecated for
  `remotePatterns`.
- `revalidateTag(tag)` is deprecated; pass a profile such as `'max'` or
  `{ expire: 0 }` for immediate expiry. `updateTag` and `refresh` are Server
  Action-only. Caching details: `cache-components`.

The params and proxy shapes, checked against next 16.3.8 (`next typegen`,
`tsc --noEmit`, `next build`):

```tsx
// app/blog/[slug]/page.tsx; PageProps is global after `next typegen` (or dev/build)
export async function generateStaticParams() {
  return [{ slug: 'hello' }] // cacheComponents: needed for this top-level await; never []
}

export default async function Page({ params }: PageProps<'/blog/[slug]'>) {
  const { slug } = await params // a Promise; sync access was removed in 16
  return <h1>{slug}</h1>
}

// proxy.ts, replacing middleware.ts: Node.js runtime, no `runtime` export
import { NextResponse, type NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  // Optimistic check only: authorize again where the data is read.
  if (request.cookies.has('session')) return NextResponse.next()
  return NextResponse.redirect(new URL('/login', request.url))
}

export const config = { matcher: ['/dashboard/:path*'] }
```

The `upgrade` codemod does not migrate synchronous request-API access; run
`next-async-request-api` separately when migrating that code. Use the project's
package runner and review the resulting types and runtime behavior.

For an authorized upgrade, `npx next@canary upgrade [app-dir] --agent=security`
(or `=latest`; experimental, documented from 16.4 in the installed
`02-guides/upgrading/agent-upgrade.md`) selects the target and prints its guides,
codemods and checks for the current agent; plain `next upgrade` runs the
interactive codemods.

Review the actual failure or feature, rather than applying every optimization.
Keep the project's router, caching mode, runtime and package manager unless
migration is requested.

## Read for the affected area

| Area | Local reference |
| --- | --- |
| Route files, groups, proxy | [File conventions](file-conventions.md) |
| Server/client imports and props | [RSC boundaries](rsc-boundaries.md), [directives](directives.md) |
| Params and request APIs | [Async APIs](async-patterns.md), [functions](functions.md) |
| Reads, mutations and APIs | [Data patterns](data-patterns.md), [Route Handlers](route-handlers.md) |
| Rendering and failures | [Suspense](suspense-boundaries.md), [hydration](hydration-error.md), [errors](error-handling.md) |
| Metadata and public discovery | [Metadata](metadata.md); `nextjs-seo` for an SEO audit |
| Assets and loading | [Images](image.md), [fonts](font.md), [scripts](scripts.md) |
| Package/runtime behavior | [Bundling](bundling.md), [runtime](runtime-selection.md) |
| Navigation slots/modals | [Parallel routes](parallel-routes.md) |
| Deployment/debugging | [Self-hosting](self-hosting.md), [diagnostics](debug-tricks.md) |

Use `cache-components` when that mode is enabled and relevant to the task.
Tag invalidation can also operate on fetch caches outside that mode.

Validate with the project's lint/typecheck scripts and a production build,
then exercise the changed route under `next start`. A dev render can
hide prerender/Suspense issues; a build cannot prove authorization, hydration,
freshness or cross-instance behavior. Report what was actually exercised.

© laguagu · MIT · laguagu/claude-code-nextjs-skills

Similar skills

All skills for Frontend and UI →

next-best-practices by other authors comes first.

next-best-practices pedronauck next-best-practices — a skill that hands your agent a set of Next.js rules: file conventions, RSC boundaries, async APIs, metadata, error handling. Useful whenever it writes or reviews Next.js code. CX Codex +1 402installs nextjs-app-architecture aurorascharff nextjs-app-architecture — a skill that keeps a Next.js 16 App Router codebase on one architecture: pages compose, features fetch. Useful when starting an app or auditing one. CX Codex +1 540installs nextjs-app-router-expert curiositech The nextjs-app-router-expert skill guides Next.js 14/15 App Router work, from route design to data loading. Use it when building or debugging server-rendered React features. CX Codex +1 176installs cra-to-next-migration community cra-to-next-migration guides code assistants through migrating Create React App codebases to Next.js 16+. It converts React Router routes, adjusts environment variables, and adopts App Router patterns. CX Codex +1 960installs Next.js App taste f Next.js App taste — a prompt for ChatGPT and Claude.ai that enforces pragmatic Next.js App Router conventions. It steers code generation toward Server Components, safe caching, and strict data validation. GP ChatGPT ★ 178,201repo stars next-intl-app-router liuchiawei next-intl-app-router sets up next-intl with locale-prefixed routes: config, proxy, navigation and message files. Useful when a project gets a second language. CX Codex +1 619installs Next.js Expert official github Next.js Expert — a Next.js 16 subagent for App Router, Server Components, caching, and TypeScript work. Use it when an agent needs to inspect or change a Next.js codebase. CX Codex +1 ★ 41,430repo stars

From the same set13

The whole set →
nextjs-seo The nextjs-seo Claude Code skill handles SEO implementation and audits for Next.js App Router. It covers metadata, indexing issues, structured data and crawler rules. CX Codex +1 2,600installs openai-agents-sdk This Claude Code skill supports Python development with the OpenAI Agents SDK. It activates for work on agent tools, handoffs, sessions, and streaming. CX Codex +1 2,500installs supabase-postgres-best-practices The supabase-postgres-best-practices skill guides agents through Postgres schema and SQL work using Supabase-maintained rules. Load it before database changes or when investigating query, connection, and RLS issues. CX Codex +1 146installs nextjs-shadcn nextjs-shadcn — a skill for Claude Code that guides Next.js and shadcn/ui development. Activates when building or refining pages, presets, layouts and design system components. CX Codex +1 861installs postgres-semantic-search The postgres-semantic-search Claude Code skill builds and tunes PostgreSQL retrieval. It covers semantic and hybrid search, evaluation, and troubleshooting weak results. CX Codex +1 227installs cache-components A skill for mastering Next.js Cache Components and Partial Prerendering in version 16.4+. Advises on the use cache directive, setting cache lifetime with cacheLife(), tagging data with cacheTag(), and invalidating via updateTag(). CX Codex +1 222installs ai-sdk-6 ai-sdk-6 — a skill for projects already on Vercel AI SDK v6. Covers building agents, chatbots, tool integrations, streaming responses and structured output with patterns specific to the v6 API. CX Codex +1 218installs ai-app A skill for Claude Code sets up full-stack Next.js AI applications with AI SDK and shadcn/ui. Activates when generating chatbots, agent dashboards, and custom AI tools. CX Codex +1 198installs

Project sponsors

Companies that keep this analytics open