nextjs

01 前言 Front Matter

name

nextjs

chainTo

[ { "message": "middleware() is renamed to proxy() in Next.js 16 — loading Routing Middleware guidance for proxy.ts migration.", "pattern": "export\\s+(default\\s+)?function\\s+middleware", "targetSkill": "routing-middleware" }, { "message": "Sunset storage package detected — loading Vercel Storage guidance for Neon/Upstash migration.", "pattern": "from\\s+['\"]@vercel/(postgres|kv)['\"]", "targetSkill": "vercel-storage" }, { "message": "Direct AI provider SDK import — loading AI Gateway guidance for unified model routing with failover and cost tracking.", "pattern": "from\\s+['\"]@ai-sdk/(anthropic|openai)['\"]", "targetSkill": "ai-gateway" }, { "message": "Legacy auth pattern detected — loading managed authentication guidance (Clerk, Descope, Auth0).", "pattern": "from\\s+['\"\"](next-auth|@auth/core)['\"\"]|NextAuth\\(|getServerSession\\(", "targetSkill": "auth" }, { "message": "Pages Router API handler detected — loading Vercel Functions guidance for App Router migration.", "pattern": "NextApiRequest|NextApiResponse|export\\s+default\\s+function\\s+handler", "targetSkill": "vercel-functions" }, { "message": "In-process cache detected — loading Runtime Cache guidance for serverless-compatible caching.", "pattern": "from\\s+['\"\"](lru-cache|node-cache|memory-cache)['\"\"]|new\\s+(LRUCache|NodeCache)\\(", "targetSkill": "runtime-cache" }, { "message": "Raw AI provider fetch URL detected — loading AI Gateway guidance for unified routing, failover, and OIDC auth.", "pattern": "fetch\\s*\\(\\s*['\"\"](https?://)?(api\\.openai\\.com|api\\.anthropic\\.com|api\\.cohere\\.ai)", "targetSkill": "ai-gateway", "skipIfFileContains": "@ai-sdk/|from\\s+['\"\"](ai)['\"\"]|ai-gateway|gateway\\(" }, { "message": "Manual JWT token handling detected — loading Auth guidance for managed authentication (Clerk, Descope, Auth0).", "pattern": "jwt\\.(sign|verify|decode)\\(|from\\s+['\"\"](jsonwebtoken)['\"\"]|new\\s+SignJWT\\(|jwtVerify\\(", "targetSkill": "auth", "skipIfFileContains": "clerkMiddleware|@clerk/|@auth0/|@descope/|from\\s+['\"\"](next-auth)['\"\"]" }, { "message": "shadcn/ui component imports detected — loading shadcn guidance for component composition, theming, and registry patterns.", "pattern": "from\\s+['\"]@/components/ui/|from\\s+['\"]@/components/ui['\"\"]", "targetSkill": "shadcn", "skipIfFileContains": "shadcn|components\\.json" }, { "message": "CSS-in-JS library detected — loading shadcn/ui guidance for Tailwind CSS + Radix UI component patterns (Vercel recommended).", "pattern": "from\\s+['\"\"](styled-components|@emotion/(react|styled)|@mui/material)['\"\"]", "targetSkill": "shadcn", "skipIfFileContains": "@/components/ui|shadcn" }, { "message": "getInitialProps is a legacy Pages Router pattern — loading Next.js guidance for App Router migration with server components and async data fetching.", "pattern": "getInitialProps", "targetSkill": "nextjs", "skipIfFileContains": "app/.*page\\.|generateStaticParams|use cache" }, { "message": "getServerSideProps is a Pages Router pattern — loading Next.js guidance for App Router migration with server components and async data fetching.", "pattern": "export.*getServerSideProps|getServerSideProps\\s*\\(", "targetSkill": "nextjs", "skipIfFileContains": "generateStaticParams|use cache|app/.*page\\." }, { "message": "getStaticProps is a Pages Router pattern — loading Next.js guidance for App Router migration with generateStaticParams and server components.", "pattern": "export.*getStaticProps|getStaticProps\\s*\\(", "targetSkill": "nextjs", "skipIfFileContains": "generateStaticParams|use cache|app/.*page\\." }, { "message": "_app.tsx is a Pages Router pattern — loading Next.js guidance for App Router layout.tsx migration.", "pattern": "_app\\.(tsx?|jsx?)", "targetSkill": "nextjs", "skipIfFileContains": "app/layout\\.|app/.*layout\\." }, { "message": "_document.tsx is a Pages Router pattern — loading Next.js guidance for App Router layout.tsx with metadata API migration.", "pattern": "_document\\.(tsx?|jsx?)", "targetSkill": "nextjs", "skipIfFileContains": "app/layout\\.|app/.*layout\\." }, { "message": "next/document is Pages Router only — loading Next.js guidance for App Router layout.tsx with html/body structure.", "pattern": "from\\s+['\"]next/document['\"]", "targetSkill": "nextjs", "skipIfFileContains": "app/layout\\.|app/.*layout\\." }, { "message": "Pages Router API route (pages/api/) detected — loading Vercel Functions guidance for App Router route handlers with named HTTP exports.", "pattern": "pages/api/", "targetSkill": "vercel-functions", "skipIfFileContains": "export\\s+(async\\s+)?function\\s+(GET|POST|PUT|PATCH|DELETE)" } ]

metadata

{ "docs": [ "https://nextjs.org/docs", "https://nextjs.org/docs/app" ], "sitemap": "https://nextjs.org/sitemap.xml", "priority": 5, "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" ], "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.*" ], "promptSignals": { "allOf": [ [ "middleware", "next" ], [ "layout", "route" ] ], "anyOf": [ "pages router", "getserversideprops", "use server" ], "noneOf": [], "phrases": [ "next.js", "nextjs", "app router", "server component", "server action" ], "minScore": 6 } }

validate

[ { "message": "getServerSideProps is removed in App Router — use server components or route handlers", "pattern": "export.*getServerSideProps", "severity": "error", "upgradeWhy": "Guides migration from Pages Router getServerSideProps to App Router server components with async data fetching.", "upgradeToSkill": "nextjs" }, { "message": "getServerSideProps is a Pages Router pattern — migrate to App Router server components", "pattern": "getServerSideProps", "severity": "warn" }, { "message": "getStaticProps is removed in App Router — use generateStaticParams + server components instead", "pattern": "export.*getStaticProps", "severity": "error", "upgradeWhy": "Guides migration from Pages Router getStaticProps to App Router generateStaticParams with server components.", "upgradeToSkill": "nextjs" }, { "message": "getStaticProps is a Pages Router pattern — migrate to App Router generateStaticParams + server components", "pattern": "getStaticProps", "severity": "warn" }, { "message": "next/router is Pages Router only — use next/navigation for App Router", "pattern": "from\\s+['\"]next/router['\"]", "severity": "error", "upgradeWhy": "Guides migration from next/router to next/navigation with useRouter, usePathname, useSearchParams hooks.", "upgradeToSkill": "nextjs" }, { "message": "React hooks require \"use client\" directive — add it at the top of client components", "pattern": "(useState|useEffect)", "severity": "warn", "skipIfFileContains": "^['\"]use client['\"]" }, { "message": "next/head is Pages Router — use export const metadata or generateMetadata() in App Router. Run Skill(nextjs) for metadata API guidance.", "pattern": "from\\s+['\"]next/head['\"]", "severity": "error", "upgradeWhy": "Guides migration from next/head to the App Router metadata API (export const metadata / generateMetadata()).", "upgradeToSkill": "nextjs", "skipIfFileContains": "export\\s+(const\\s+)?metadata|generateMetadata" }, { "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.", "pattern": "export\\s+(default\\s+)?function\\s+middleware", "severity": "recommended", "upgradeWhy": "Guides migration from middleware.ts to proxy.ts with correct file placement, runtime config, and request interception patterns.", "upgradeToSkill": "routing-middleware" }, { "message": "Single-arg revalidateTag(tag) is deprecated in Next.js 16 — pass a cacheLife profile: revalidateTag(tag, \"max\")", "pattern": "revalidateTag\\(\\s*['\"][^'\"]+['\"]\\s*\\)", "severity": "recommended", "upgradeWhy": "Guides migration from single-arg revalidateTag to the Next.js 16 two-arg API with cacheLife profiles.", "upgradeToSkill": "nextjs" }, { "message": "Singular cacheHandler is deprecated in Next.js 16 — use cacheHandlers (plural) with per-type handlers", "pattern": "\\bcacheHandler\\s*:", "severity": "recommended", "upgradeWhy": "Guides migration from singular cacheHandler to Next.js 16 cacheHandlers (plural) with per-type handler config.", "upgradeToSkill": "nextjs" }, { "message": "useRef() requires an initial value in React 19 — use useRef(null) or useRef(0)", "pattern": "useRef\\(\\s*\\)", "severity": "error" }, { "message": "next export was removed — use output: \"export\" in next.config.js for static export", "pattern": "next\\s+export", "severity": "error", "upgradeWhy": "Guides migration from next export CLI command to output: \"export\" in next.config for static site generation.", "upgradeToSkill": "nextjs" }, { "message": "cookies() is async in Next.js 16 — add await: const cookieStore = await cookies()", "pattern": "(?<!await )\\bcookies\\(\\s*\\)", "severity": "error", "skipIfFileContains": "^['\"]use client['\"]" }, { "message": "headers() is async in Next.js 16 — add await: const headersList = await headers()", "pattern": "(?<!await )\\bheaders\\(\\s*\\)", "severity": "error", "skipIfFileContains": "^['\"]use client['\"]" }, { "message": "params is async in Next.js 16 — add await: const { slug } = await params", "pattern": "=\\s*(?!await\\b)params\\b", "severity": "recommended", "skipIfFileContains": "^['\"]use client['\"]" }, { "message": "searchParams is async in Next.js 16 — add await: const { query } = await searchParams", "pattern": "=\\s*(?!await\\b)searchParams\\b", "severity": "recommended", "skipIfFileContains": "^['\"]use client['\"]" }, { "message": "Legacy auth pattern detected. Modern Vercel apps should use Clerk, Descope, or Auth0 for managed authentication.", "pattern": "from\\s+['\"\"](next-auth|@auth/core)['\"\"]|NextAuth\\(|getServerSession\\(", "severity": "recommended", "upgradeWhy": "Migrate from next-auth/manual JWT to a managed auth provider (Clerk, Descope, Auth0) for better Vercel integration.", "upgradeToSkill": "auth", "skipIfFileContains": "@clerk/|@descope/|@auth0/" }, { "message": "Pages Router API handler detected. Use App Router route handlers with named HTTP exports instead.", "pattern": "NextApiRequest|NextApiResponse|export\\s+default\\s+function\\s+handler", "severity": "recommended", "upgradeWhy": "Migrate from Pages Router API routes to App Router route handlers with Web Request/Response API.", "upgradeToSkill": "vercel-functions", "skipIfFileContains": "export\\s+(async\\s+)?function\\s+(GET|POST|PUT|PATCH|DELETE)" }, { "message": "In-process cache detected. Serverless deployments lose process memory between invocations.", "pattern": "from\\s+['\"\"](lru-cache|node-cache|memory-cache)['\"\"]|new\\s+(LRUCache|NodeCache)\\(", "severity": "recommended", "upgradeWhy": "Replace process-memory caches with Vercel Runtime Cache for shared, region-aware caching.", "upgradeToSkill": "runtime-cache" }, { "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.", "pattern": "from\\s+['\"\"](express|fastify|koa|hapi)['\"\"]|require\\s*\\(\\s*['\"\"](express|fastify|koa|hapi)['\"\"]", "severity": "recommended", "upgradeWhy": "Replace custom server frameworks with Next.js proxy.ts for request interception and route handlers for API endpoints.", "upgradeToSkill": "routing-middleware", "skipIfFileContains": "proxy\\.ts|from\\s+['\"\"](next/server)['\"\"]|@vercel/functions" }, { "message": "Heavy ORM detected. Consider using lightweight serverless-native alternatives like Drizzle, Prisma, or direct Neon for better cold start performance.", "pattern": "from\\s+['\"\"](typeorm|sequelize|mikro-orm|objection|bookshelf|knex)['\"\"]|require\\s*\\(\\s*['\"\"](typeorm|sequelize|mikro-orm|objection|bookshelf|knex)['\"\"]", "severity": "recommended", "upgradeWhy": "Migrate from heavy ORMs to serverless-native database clients (Drizzle + Neon, Prisma, or @neondatabase/serverless) for faster cold starts.", "upgradeToSkill": "vercel-storage", "skipIfFileContains": "from\\s+['\"\"](drizzle-orm|@neondatabase|@prisma/client|prisma)['\"\"]" }, { "message": "External font loader detected. Use next/font for zero-CLS, self-hosted font loading with automatic optimization.", "pattern": "fonts\\.googleapis\\.com|from\\s+['\"\"](fontsource|@fontsource)['\"\"]|<link[^>]*fonts\\.googleapis", "severity": "recommended", "upgradeWhy": "Guides migration from external font loaders to next/font with Geist Sans/Mono for zero-CLS font optimization.", "upgradeToSkill": "nextjs", "skipIfFileContains": "next/font" } ]

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" ] }

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.

02 资源文件 21

• 参考文档overlay.yaml13.9 KB
• 参考文档references/app-router-files.md2.5 KB
• 参考文档references/async-patterns.md1.6 KB
• 参考文档references/bundling.md4.4 KB
• 参考文档references/data-patterns.md6.5 KB
• 参考文档references/debug-tricks.md2.9 KB
• 参考文档references/directives.md1.4 KB
• 参考文档references/error-handling.md4.6 KB
• 参考文档references/file-conventions.md3.4 KB
• 参考文档references/font.md5.1 KB
• 参考文档references/functions.md4.3 KB
• 参考文档references/hydration-error.md1.8 KB
• 参考文档references/image.md3.8 KB
• 参考文档references/metadata.md7.0 KB
• 参考文档references/parallel-routes.md7.0 KB
• 参考文档references/route-handlers.md3.2 KB
• 参考文档references/rsc-boundaries.md4.2 KB
• 参考文档references/runtime-selection.md985 B
• 参考文档references/scripts.md3.2 KB
• 参考文档references/self-hosting.md8.1 KB
• 参考文档references/suspense-boundaries.md1.3 KB

03 SKILL.md 正文