next-best-practices

name	next-best-practices
description	Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling.
metadata	{"priority":5,"docs":["https://nextjs.org/docs","https://nextjs.org/docs/app"],"sitemap":"https://nextjs.org/sitemap.xml","pathPatterns":["next.config.*","next-env.d.ts","app/**","pages/**","src/app/**","src/pages/**","tailwind.config.*","postcss.config.*","tsconfig.json","tsconfig.*.json","apps/*/app/**","apps/*/pages/**","apps/*/src/app/**","apps/*/src/pages/**","apps/*/next.config.*"],"bashPatterns":["\\bnext\\s+(dev|build|start|lint)\\b","\\bnext\\s+experimental-analyze\\b","\\bnpx\\s+create-next-app\\b","\\bbunx\\s+create-next-app\\b","\\bnpm\\s+run\\s+(dev|build|start)\\b","\\bpnpm\\s+(dev|build)\\b","\\bbun\\s+run\\s+(dev|build)\\b"],"promptSignals":{"phrases":["next.js","nextjs","app router","server component","server action"],"allOf":[["middleware","next"],["layout","route"]],"anyOf":["pages router","getserversideprops","use server"],"noneOf":[],"minScore":6}}
validate	[{"pattern":"export.*getServerSideProps","message":"getServerSideProps is removed in App Router — use server components or route handlers","severity":"error","upgradeToSkill":"nextjs","upgradeWhy":"Guides migration from Pages Router getServerSideProps to App Router server components with async data fetching."},{"pattern":"getServerSideProps","message":"getServerSideProps is a Pages Router pattern — migrate to App Router server components","severity":"warn"},{"pattern":"export.*getStaticProps","message":"getStaticProps is removed in App Router — use generateStaticParams + server components instead","severity":"error","upgradeToSkill":"nextjs","upgradeWhy":"Guides migration from Pages Router getStaticProps to App Router generateStaticParams with server components."},{"pattern":"getStaticProps","message":"getStaticProps is a Pages Router pattern — migrate to App Router generateStaticParams + server components","severity":"warn"},{"pattern":"from\\s+['\"]next/router['\"]","message":"next/router is Pages Router only — use next/navigation for App Router","severity":"error","upgradeToSkill":"nextjs","upgradeWhy":"Guides migration from next/router to next/navigation with useRouter, usePathname, useSearchParams hooks."},{"pattern":"(useState|useEffect)","message":"React hooks require \"use client\" directive — add it at the top of client components","severity":"warn","skipIfFileContains":"^['\"]use client['\"]"},{"pattern":"from\\s+['\"]next/head['\"]","message":"next/head is Pages Router — use export const metadata or generateMetadata() in App Router. Run Skill(nextjs) for metadata API guidance.","severity":"error","upgradeToSkill":"nextjs","upgradeWhy":"Guides migration from next/head to the App Router metadata API (export const metadata / generateMetadata()).","skipIfFileContains":"export\\s+(const\\s+)?metadata|generateMetadata"},{"pattern":"export\\s+(default\\s+)?function\\s+middleware","message":"middleware() is renamed to proxy() in Next.js 16 — rename the function and the file to proxy.ts. Run Skill(routing-middleware) for proxy.ts migration guidance.","severity":"recommended","upgradeToSkill":"routing-middleware","upgradeWhy":"Guides migration from middleware.ts to proxy.ts with correct file placement, runtime config, and request interception patterns."},{"pattern":"revalidateTag\\(\\s*['\"][^'\"]+['\"]\\s*\\)","message":"Single-arg revalidateTag(tag) is deprecated in Next.js 16 — pass a cacheLife profile: revalidateTag(tag, \"max\")","severity":"recommended","upgradeToSkill":"nextjs","upgradeWhy":"Guides migration from single-arg revalidateTag to the Next.js 16 two-arg API with cacheLife profiles."},{"pattern":"\\bcacheHandler\\s*:","message":"Singular cacheHandler is deprecated in Next.js 16 — use cacheHandlers (plural) with per-type handlers","severity":"recommended","upgradeToSkill":"nextjs","upgradeWhy":"Guides migration from singular cacheHandler to Next.js 16 cacheHandlers (plural) with per-type handler config."},{"pattern":"useRef\\(\\s*\\)","message":"useRef() requires an initial value in React 19 — use useRef(null) or useRef(0)","severity":"error"},{"pattern":"next\\s+export","message":"next export was removed — use output: \"export\" in next.config.js for static export","severity":"error","upgradeToSkill":"nextjs","upgradeWhy":"Guides migration from next export CLI command to output: \"export\" in next.config for static site generation."},{"pattern":"(?<!await )\\bcookies\\(\\s*\\)","message":"cookies() is async in Next.js 16 — add await: const cookieStore = await cookies()","severity":"error","skipIfFileContains":"^['\"]use client['\"]"},{"pattern":"(?<!await )\\bheaders\\(\\s*\\)","message":"headers() is async in Next.js 16 — add await: const headersList = await headers()","severity":"error","skipIfFileContains":"^['\"]use client['\"]"},{"pattern":"=\\s*(?!await\\b)params\\b","message":"params is async in Next.js 16 — add await: const { slug } = await params","severity":"recommended","skipIfFileContains":"^['\"]use client['\"]"},{"pattern":"=\\s*(?!await\\b)searchParams\\b","message":"searchParams is async in Next.js 16 — add await: const { query } = await searchParams","severity":"recommended","skipIfFileContains":"^['\"]use client['\"]"},{"pattern":"from\\s+['\"\"](next-auth|@auth/core)['\"\"]|NextAuth\\(|getServerSession\\(","message":"Legacy auth pattern detected. Modern Vercel apps should use Clerk, Descope, or Auth0 for managed authentication.","severity":"recommended","upgradeToSkill":"auth","upgradeWhy":"Migrate from next-auth/manual JWT to a managed auth provider (Clerk, Descope, Auth0) for better Vercel integration.","skipIfFileContains":"@clerk/|@descope/|@auth0/"},{"pattern":"NextApiRequest|NextApiResponse|export\\s+default\\s+function\\s+handler","message":"Pages Router API handler detected. Use App Router route handlers with named HTTP exports instead.","severity":"recommended","upgradeToSkill":"vercel-functions","upgradeWhy":"Migrate from Pages Router API routes to App Router route handlers with Web Request/Response API.","skipIfFileContains":"export\\s+(async\\s+)?function\\s+(GET|POST|PUT|PATCH|DELETE)"},{"pattern":"from\\s+['\"\"](lru-cache|node-cache|memory-cache)['\"\"]|new\\s+(LRUCache|NodeCache)\\(","message":"In-process cache detected. Serverless deployments lose process memory between invocations.","severity":"recommended","upgradeToSkill":"runtime-cache","upgradeWhy":"Replace process-memory caches with Vercel Runtime Cache for shared, region-aware caching."},{"pattern":"from\\s+['\"\"](express|fastify|koa|hapi)['\"\"]|require\\s*\\(\\s*['\"\"](express|fastify|koa|hapi)['\"\"]","message":"Express/Fastify/Koa/Hapi server framework detected in a Next.js project. Use Next.js route handlers or proxy.ts for request handling instead.","severity":"recommended","upgradeToSkill":"routing-middleware","upgradeWhy":"Replace custom server frameworks with Next.js proxy.ts for request interception and route handlers for API endpoints.","skipIfFileContains":"proxy\\.ts|from\\s+['\"\"](next/server)['\"\"]|@vercel/functions"},{"pattern":"from\\s+['\"\"](typeorm|sequelize|mikro-orm|objection|bookshelf|knex)['\"\"]|require\\s*\\(\\s*['\"\"](typeorm|sequelize|mikro-orm|objection|bookshelf|knex)['\"\"]","message":"Heavy ORM detected. Consider using lightweight serverless-native alternatives like Drizzle, Prisma, or direct Neon for better cold start performance.","severity":"recommended","upgradeToSkill":"vercel-storage","upgradeWhy":"Migrate from heavy ORMs to serverless-native database clients (Drizzle + Neon, Prisma, or @neondatabase/serverless) for faster cold starts.","skipIfFileContains":"from\\s+['\"\"](drizzle-orm|@neondatabase|@prisma/client|prisma)['\"\"]"},{"pattern":"fonts\\.googleapis\\.com|from\\s+['\"\"](fontsource|@fontsource)['\"\"]|<link[^>]*fonts\\.googleapis","message":"External font loader detected. Use next/font for zero-CLS, self-hosted font loading with automatic optimization.","severity":"recommended","upgradeToSkill":"nextjs","upgradeWhy":"Guides migration from external font loaders to next/font with Geist Sans/Mono for zero-CLS font optimization.","skipIfFileContains":"next/font"}]
chainTo	[{"pattern":"export\\s+(default\\s+)?function\\s+middleware","targetSkill":"routing-middleware","message":"middleware() is renamed to proxy() in Next.js 16 — loading Routing Middleware guidance for proxy.ts migration."},{"pattern":"from\\s+['\"]@vercel/(postgres|kv)['\"]","targetSkill":"vercel-storage","message":"Sunset storage package detected — loading Vercel Storage guidance for Neon/Upstash migration."},{"pattern":"from\\s+['\"]@ai-sdk/(anthropic|openai)['\"]","targetSkill":"ai-gateway","message":"Direct AI provider SDK import — loading AI Gateway guidance for unified model routing with failover and cost tracking."},{"pattern":"from\\s+['\"\"](next-auth|@auth/core)['\"\"]|NextAuth\\(|getServerSession\\(","targetSkill":"auth","message":"Legacy auth pattern detected — loading managed authentication guidance (Clerk, Descope, Auth0)."},{"pattern":"NextApiRequest|NextApiResponse|export\\s+default\\s+function\\s+handler","targetSkill":"vercel-functions","message":"Pages Router API handler detected — loading Vercel Functions guidance for App Router migration."},{"pattern":"from\\s+['\"\"](lru-cache|node-cache|memory-cache)['\"\"]|new\\s+(LRUCache|NodeCache)\\(","targetSkill":"runtime-cache","message":"In-process cache detected — loading Runtime Cache guidance for serverless-compatible caching."},{"pattern":"fetch\\s*\\(\\s*['\"\"](https?://)?(api\\.openai\\.com|api\\.anthropic\\.com|api\\.cohere\\.ai)","targetSkill":"ai-gateway","message":"Raw AI provider fetch URL detected — loading AI Gateway guidance for unified routing, failover, and OIDC auth.","skipIfFileContains":"@ai-sdk/|from\\s+['\"\"](ai)['\"\"]|ai-gateway|gateway\\("},{"pattern":"jwt\\.(sign|verify|decode)\\(|from\\s+['\"\"](jsonwebtoken)['\"\"]|new\\s+SignJWT\\(|jwtVerify\\(","targetSkill":"auth","message":"Manual JWT token handling detected — loading Auth guidance for managed authentication (Clerk, Descope, Auth0).","skipIfFileContains":"clerkMiddleware|@clerk/|@auth0/|@descope/|from\\s+['\"\"](next-auth)['\"\"]"},{"pattern":"from\\s+['\"]@/components/ui/|from\\s+['\"]@/components/ui['\"\"]","targetSkill":"shadcn","message":"shadcn/ui component imports detected — loading shadcn guidance for component composition, theming, and registry patterns.","skipIfFileContains":"shadcn|components\\.json"},{"pattern":"from\\s+['\"\"](styled-components|@emotion/(react|styled)|@mui/material)['\"\"]","targetSkill":"shadcn","message":"CSS-in-JS library detected — loading shadcn/ui guidance for Tailwind CSS + Radix UI component patterns (Vercel recommended).","skipIfFileContains":"@/components/ui|shadcn"},{"pattern":"getInitialProps","targetSkill":"nextjs","message":"getInitialProps is a legacy Pages Router pattern — loading Next.js guidance for App Router migration with server components and async data fetching.","skipIfFileContains":"app/.*page\\.|generateStaticParams|use cache"},{"pattern":"export.*getServerSideProps|getServerSideProps\\s*\\(","targetSkill":"nextjs","message":"getServerSideProps is a Pages Router pattern — loading Next.js guidance for App Router migration with server components and async data fetching.","skipIfFileContains":"generateStaticParams|use cache|app/.*page\\."},{"pattern":"export.*getStaticProps|getStaticProps\\s*\\(","targetSkill":"nextjs","message":"getStaticProps is a Pages Router pattern — loading Next.js guidance for App Router migration with generateStaticParams and server components.","skipIfFileContains":"generateStaticParams|use cache|app/.*page\\."},{"pattern":"_app\\.(tsx?|jsx?)","targetSkill":"nextjs","message":"_app.tsx is a Pages Router pattern — loading Next.js guidance for App Router layout.tsx migration.","skipIfFileContains":"app/layout\\.|app/.*layout\\."},{"pattern":"_document\\.(tsx?|jsx?)","targetSkill":"nextjs","message":"_document.tsx is a Pages Router pattern — loading Next.js guidance for App Router layout.tsx with metadata API migration.","skipIfFileContains":"app/layout\\.|app/.*layout\\."},{"pattern":"from\\s+['\"]next/document['\"]","targetSkill":"nextjs","message":"next/document is Pages Router only — loading Next.js guidance for App Router layout.tsx with html/body structure.","skipIfFileContains":"app/layout\\.|app/.*layout\\."},{"pattern":"pages/api/","targetSkill":"vercel-functions","message":"Pages Router API route (pages/api/) detected — loading Vercel Functions guidance for App Router route handlers with named HTTP exports.","skipIfFileContains":"export\\s+(async\\s+)?function\\s+(GET|POST|PUT|PATCH|DELETE)"}]
retrieval	{"aliases":["next.js","nextjs app","react framework","app router"],"intents":["set up routing and layouts in a Next.js app","choose between server and client components for a feature","configure data fetching or caching in App Router","add middleware or proxy logic to handle requests","set up server rendering for React pages","add a new page with dynamic route segments"],"entities":["App Router","Server Components","Server Actions","generateMetadata","layout","proxy","next.config"],"examples":["add a new page with dynamic routing","should this be a server or client component","set up middleware for auth redirects","configure caching for this data fetch","set up server rendering for my pages"]}

Next.js Best Practices

Apply these rules when writing or reviewing Next.js code.

File Conventions

See file-conventions.md for:

• Project structure and special files
• Route segments (dynamic, catch-all, groups)
• Parallel and intercepting routes
• Middleware rename in v16 (middleware → proxy)

RSC Boundaries

Detect invalid React Server Component patterns.

See rsc-boundaries.md for:

• Async client component detection (invalid)
• Non-serializable props detection
• Server Action exceptions

Async Patterns

Next.js 15+ async API changes.

See async-patterns.md for:

• Async params and searchParams
• Async cookies() and headers()
• Migration codemod

Runtime Selection

See runtime-selection.md for:

• Default to Node.js runtime
• When Edge runtime is appropriate

Directives

See directives.md for:

• 'use client', 'use server' (React)
• 'use cache' (Next.js)

Functions

See functions.md for:

• Navigation hooks: useRouter, usePathname, useSearchParams, useParams
• Server functions: cookies, headers, draftMode, after
• Generate functions: generateStaticParams, generateMetadata

Error Handling

See error-handling.md for:

• error.tsx, global-error.tsx, not-found.tsx
• redirect, permanentRedirect, notFound
• forbidden, unauthorized (auth errors)
• unstable_rethrow for catch blocks

Data Patterns

See data-patterns.md for:

• Server Components vs Server Actions vs Route Handlers
• Avoiding data waterfalls (Promise.all, Suspense, preload)
• Client component data fetching

Route Handlers

See route-handlers.md for:

• route.ts basics
• GET handler conflicts with page.tsx
• Environment behavior (no React DOM)
• When to use vs Server Actions

Metadata & OG Images

See metadata.md for:

• Static and dynamic metadata
• generateMetadata function
• OG image generation with next/og
• File-based metadata conventions

Image Optimization

See image.md for:

• Always use next/image over <img>
• Remote images configuration
• Responsive sizes attribute
• Blur placeholders
• Priority loading for LCP

Font Optimization

See font.md for:

• next/font setup
• Google Fonts, local fonts
• Tailwind CSS integration
• Preloading subsets

Bundling

See bundling.md for:

• Server-incompatible packages
• CSS imports (not link tags)
• Polyfills (already included)
• ESM/CommonJS issues
• Bundle analysis

Scripts

See scripts.md for:

• next/script vs native script tags
• Inline scripts need id
• Loading strategies
• Google Analytics with @next/third-parties

Hydration Errors

See hydration-error.md for:

• Common causes (browser APIs, dates, invalid HTML)
• Debugging with error overlay
• Fixes for each cause

Suspense Boundaries

See suspense-boundaries.md for:

• CSR bailout with useSearchParams and usePathname
• Which hooks require Suspense boundaries

Parallel & Intercepting Routes

See parallel-routes.md for:

• Modal patterns with @slot and (.) interceptors
• default.tsx for fallbacks
• Closing modals correctly with router.back()

Self-Hosting

See self-hosting.md for:

• output: 'standalone' for Docker
• Cache handlers for multi-instance ISR
• What works vs needs extra setup

Debug Tricks

See debug-tricks.md for:

• MCP endpoint for AI-assisted debugging
• Rebuild specific routes with --debug-build-paths