nextjs
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.
- License 许可
- MIT
- 最近更新
- 2026-03-27
- Stars
- ★ 3
- Forks
- 1
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 资源文件 22
- 参考文档overlay.yaml13.9 KB
- 参考文档patterns.md5.7 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 正文
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
paramsandsearchParams - Async
cookies()andheaders() - 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.tsxredirect,permanentRedirect,notFoundforbidden,unauthorized(auth errors)unstable_rethrowfor 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.tsbasics- 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
generateMetadatafunction- OG image generation with
next/og - File-based metadata conventions
Image Optimization
See image.md for:
- Always use
next/imageover<img> - Remote images configuration
- Responsive
sizesattribute - Blur placeholders
- Priority loading for LCP
Font Optimization
See font.md for:
next/fontsetup- 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/scriptvs 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
useSearchParamsandusePathname - Which hooks require Suspense boundaries
Parallel & Intercepting Routes
See parallel-routes.md for:
- Modal patterns with
@slotand(.)interceptors default.tsxfor 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
04 同仓库更多 Skills
zustand
Zustand state management guide. Use when working with store code (src/store/**), implementing actions, managing state, or creating slices. Triggers on Zustand store development, state management questions, or action implementation.
web-vitals
暂无简介
vercel-storage
Vercel storage expert guidance — Blob, Edge Config, and Marketplace storage (Neon Postgres, Upstash Redis). Use when choosing, configuring, or using data storage with Vercel applications.
vercel-functions
Vercel Functions expert guidance — Serverless Functions, Edge Functions, Fluid Compute, streaming, Cron Jobs, and runtime configuration. Use when configuring, debugging, or optimizing server-side code running on Vercel.
ui-ux-pro-max
UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn/ui MCP for component search and examples.
turborepo
Turborepo monorepo build system guidance. Triggers on: turbo.json, task pipelines, dependsOn, caching, remote cache, the "turbo" CLI, --filter, --affected, CI optimization, environment variables, internal packages, monorepo structure/best practices, and boundaries. Use when user: configures tasks/workflows/pipelines, creates packages, sets up monorepo, shares code between apps, runs changed/affected packages, debugs cache, or has apps/packages directories.