/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: 'cacheHandler (singular) is for ISR/route handler/image caching, not the use cache directive — for that, use cacheHandlers (plural) instead' severity: recommended upgradeToSkill: nextjs upgradeWhy: 'Explains that cacheHandler (singular, ISR/route handler/image caching) and cacheHandlers (plural, for the use cache directive) are separate, non-interchangeable Next.js configs.' - 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