AGENT SKILL

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

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 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

04 同仓库更多 Skills

ByeongminLee
ByeongminLee/nextjs-claude-code

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.

★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

web-vitals

暂无简介

★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

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.

后端与接口
★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

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.

开发工程师后端与接口
★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

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.

设计师数据分析师前端开发视觉设计
★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

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.

★ 3