laguagu/claude-code-nextjs-skills / skills/next-best-practices
next-best-practices
VerifiedNext.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),searchParamsand sitemapidare promises.next typegengenerates globalPageProps<'/route'>,LayoutPropsandRouteContexttypes. middleware.tsis deprecated:proxy.tsexportingproxy(or default) runs on Node.js only and rejects aruntimeoption; code that needs Edge stays inmiddleware.ts. Codemod:npx @next/codemod@latest middleware-to-proxy ..- Turbopack is the default for
devandbuild; a customwebpackconfig fails the build unless--webpackkeeps it or explicit--turbopackignores it.next lintis removed andnext buildno longer lints.serverRuntimeConfig/publicRuntimeConfigare removed. - Every parallel-route slot needs
default.tsx, or the build fails. next/image:priorityis deprecated forpreload;qualitiesdefaults to[75](otherqualityvalues are coerced); localsrcwith a query string needsimages.localPatterns;images.domainsis deprecated forremotePatterns.revalidateTag(tag)is deprecated; pass a profile such as'max'or{ expire: 0 }for immediate expiry.updateTagandrefreshare Server Action-only. Caching details:cache-components.
The params and proxy shapes, checked against next 16.3.8 (next typegen,
tsc --noEmit, next build):
// 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 |
| Server/client imports and props | RSC boundaries, directives |
| Params and request APIs | Async APIs, functions |
| Reads, mutations and APIs | Data patterns, Route Handlers |
| Rendering and failures | Suspense, hydration, errors |
| Metadata and public discovery | Metadata; nextjs-seo for an SEO audit |
| Assets and loading | Images, fonts, scripts |
| Package/runtime behavior | Bundling, runtime |
| Navigation slots/modals | Parallel routes |
| Deployment/debugging | Self-hosting, diagnostics |
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |