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
npx skills add laguagu/claude-code-nextjs-skills --skill next-best-practices -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/next-best-practices/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/next-best-practices/
1Skills CLI (Vercel)
npx skills add laguagu/claude-code-nextjs-skills --skill next-best-practices -a codex2Manually: put the files in place
.agents/skills/next-best-practices/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add laguagu/claude-code-nextjs-skills --skill next-best-practices -a cursor2Manually: put the files in place
.cursor/skills/next-best-practices/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install laguagu/claude-code-nextjs-skills skills/next-best-practices2Manually: put the files in place
.github/skills/next-best-practices/SKILL.md1Skills CLI (Vercel)
npx skills add laguagu/claude-code-nextjs-skills --skill next-best-practices -a gemini-cli2Platform CLI
gemini skills install https://github.com/laguagu/claude-code-nextjs-skills --path skills/next-best-practicesManually: put the files in place
.devin/skills/next-best-practices/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add laguagu/claude-code-nextjs-skills --skill next-best-practices -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.