nextjs

---

name: nextjs description: Next.js App Router expert guidance. Use when building, debugging, or architecting Next.js applications — routing, Server Components, Server Actions, Cache Components, layouts, middleware/proxy, data fetching, rendering strategies, and deployment on Vercel. 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+''""[''""]|require\s*(\s*''""[''""]' 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+''""[''""]|@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+''""[''""]|<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+''""[''""]|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+''""[''""]|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+''""[''""]|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+''""[''""]'

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+''""[''""]' 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