菜单
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.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/openai/plugins --skill nextjs命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Use this skill when implementing a Figma design as code (design → code) — the read-FROM-Figma direction. Triggers: 'implement this Figma design', 'build this screen from Figma', 'turn this Figma into code', 'code this up from Figma', 'design to code', or a figma.com design URL provided alongside a codebase. Encodes the workflow for reading a node out of Figma with get_design_context and adapting its reference output to the target project — reusing existing components, tokens, and conventions, and honoring Code Connect mappings, component docs, design annotations, and design tokens by priority. Complements figma-code-connect (component mapping) and figma-generate-design / figma-use (the reverse, code → design direction).
Use this skill alongside figma-use when the task involves translating an application page, view, or multi-section layout into Figma. Triggers: 'write to Figma', 'create in Figma from code', 'push page to Figma', 'take this app/page and build it in Figma', 'create a screen', 'build a landing page in Figma', 'update the Figma screen to match code', 'convert this modal/dialog/drawer/panel to Figma'. This is the preferred workflow skill whenever the user wants to build or update a full page, modal, dialog, drawer, sidebar, panel, or any composed multi-section view in Figma from code or a description. Discovers design system components, variables, and styles from Code Connect files, existing screens, and library search, then imports them and assembles views incrementally section-by-section using design system tokens instead of hardcoded values.
Build or update a professional-grade design system in Figma from a codebase. Use when the user wants to create variables/tokens, build component libraries, create individual components with proper variant sets and variable bindings, set up theming (light/dark modes), document foundations, or reconcile gaps between code and Figma. Also use when the user asks to create or generate any component in Figma — even a single one — since components require proper variable foundations, variant states, and design token bindings to be production-quality. This skill teaches WHAT to build and in WHAT ORDER — it complements the `figma-use` skill which teaches HOW to call the Plugin API. Both skills should be loaded together.
基于 SOC 职业分类
正在显示 SKILL.md
| 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}} |
You are an expert in Next.js 16 with the App Router. Always prefer the App Router over the legacy Pages Router unless the user's project explicitly uses Pages Router.
Never initialize database clients (Neon, Drizzle), Redis (Upstash), or service SDKs (Resend, Slack) at module scope.
During next build, static generation can evaluate modules before runtime env vars are present, which causes startup crashes. Always initialize these clients lazily inside getter functions.
import { drizzle } from 'drizzle-orm/neon-http'
import { neon } from '@neondatabase/serverless'
let _db: ReturnType<typeof drizzle> | null = null
export function getDb() {
if (!_db) _db = drizzle(neon(process.env.DATABASE_URL!))
return _db
}
Apply the same lazy singleton pattern to Redis and SDK clients (getRedis(), getResend(), getSlackClient()) instead of creating them at import time.
When running create-next-app, always pass --yes to skip interactive prompts (React Compiler, import alias) that hang in non-interactive shells:
npx create-next-app@latest my-app --yes --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --turbopack --use-npm
If the target directory contains ANY non-Next.js files (.git/, config files, etc.), you MUST add --force. Without it, create-next-app will fail with "The directory contains files that could conflict" and block scaffolding. Check the directory first — if it has anything in it, use --force:
npx create-next-app@latest . --yes --force --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --turbopack --use-npm
shadcn init rewrites globals.css with --font-sans: var(--font-sans) in @theme inline — a circular reference that falls back to Times/serif. Even var(--font-geist-sans) doesn't work because Tailwind v4's @theme inline resolves at CSS parse time, not runtime.
Two fixes required after create-next-app + shadcn init:
globals.css (not CSS variable references):@theme inline {
/* CORRECT — literal names that @theme can resolve at parse time */
--font-sans: "Geist", "Geist Fallback", ui-sans-serif, system-ui, sans-serif;
--font-mono: "Geist Mono", "Geist Mono Fallback", ui-monospace, monospace;
}
<body> to <html> in layout.tsx:// app/layout.tsx — CORRECT
<html lang="en" className={`${geistSans.variable} ${geistMono.variable}`}>
<body className="antialiased">
// app/layout.tsx — WRONG (default scaffold output)
<html lang="en">
<body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
Always apply both fixes after running create-next-app + shadcn init with Tailwind v4.
When building pages, layouts, and route-level UI in this stack, default to shadcn/ui + Geist instead of raw Tailwind scaffolding.
bg-background text-foreground, not ad-hoc palette classes.Next.js 16 uses React 19.2 features and the App Router (file-system routing under app/). Ensure React 19.2.4+ for security patches (see CVE section below).
layout.tsx — Persistent wrapper, preserves state across navigationspage.tsx — Unique UI for a route, makes route publicly accessibleloading.tsx — Suspense fallback shown while segment loadserror.tsx — Error boundary for a segmentnot-found.tsx — 404 UI for a segmentroute.ts — API endpoint (Route Handler)template.tsx — Like layout but re-mounts on navigationdefault.tsx — Fallback for parallel routes[id], catch-all: [...slug], optional catch-all: [[...slug]](group) — organize without affecting URL@slot — render multiple pages in same layout(.), (..), (...), (..)(..) — modal patternsAll components in the App Router are Server Components by default. They:
await data (fetch, DB queries, file system)useState, useEffect, or browser APIsonClick, onChange)// app/users/page.tsx — Server Component (default)
export default async function UsersPage() {
const users = await db.query('SELECT * FROM users')
return <UserList users={users} />
}
Add 'use client' at the top of the file when you need interactivity or browser APIs.
'use client'
import { useState } from 'react'
export function Counter() {
const [count, setCount] = useState(0)
return <button onClick={() => setCount(count + 1)}>{count}</button>
}
Rule: Push 'use client' as far down the component tree as possible. Keep data fetching in Server Components and pass data down as props.
Async functions marked with 'use server' that run on the server. Use for mutations.
// app/actions.ts
'use server'
export async function createUser(formData: FormData) {
const name = formData.get('name') as string
await db.insert('users', { name })
revalidatePath('/users')
}
Use Server Actions for:
revalidatePath / revalidateTagUse Route Handlers (route.ts) for:
The 'use cache' directive enables component and function-level caching.
'use cache'
export async function CachedUserList() {
cacheLife('hours') // Configure cache duration
cacheTag('users') // Tag for on-demand invalidation
const users = await db.query('SELECT * FROM users')
return <UserList users={users} />
}
'use cache' supports scope modifiers that control where cached data is stored:
// Default — cached in the deployment's local data cache
'use cache'
// Remote cache — shared across all deployments and regions (Vercel only)
'use cache: remote'
// Private cache — per-request cache, never shared between users
'use cache: private'
| Variant | Shared across deployments? | Shared across users? | Use case |
|---|---|---|---|
'use cache' | No (per-deployment) | Yes | Default, most use cases |
'use cache: remote' | Yes | Yes | Expensive computations shared globally |
'use cache: private' | No | No | User-specific cached data (e.g., profile) |
Next.js 16 uses cacheHandlers (plural) to configure separate handlers for different cache types:
// next.config.ts
const nextConfig = {
cacheHandlers: {
default: require.resolve('./cache-handler-default.mjs'),
remote: require.resolve('./cache-handler-remote.mjs'),
fetch: require.resolve('./cache-handler-fetch.mjs'),
},
}
Important: cacheHandlers (plural, Next.js 16+) replaces cacheHandler (singular, Next.js 15). The singular form configured one handler for all cache types. The plural form allows per-type handlers (default, remote, fetch). Using the old singular cacheHandler in Next.js 16 triggers a deprecation warning.
Invalidate with updateTag('users') from a Server Action (immediate expiration, Server Actions only) or revalidateTag('users', 'max') for stale-while-revalidate from Server Actions or Route Handlers.
Important: The single-argument revalidateTag(tag) is deprecated in Next.js 16. Always pass a cacheLife profile as the second argument (e.g., 'max', 'hours', 'days').
| Function | Context | Behavior |
|---|---|---|
updateTag(tag) | Server Actions only | Immediate expiration, read-your-own-writes |
revalidateTag(tag, 'max') | Server Actions + Route Handlers | Stale-while-revalidate (recommended) |
revalidateTag(tag, { expire: 0 }) | Route Handlers (webhooks) | Immediate expiration from external triggers |
In Next.js 16, middleware.ts is renamed to proxy.ts. It runs exclusively on the Node.js runtime — the Edge runtime is not supported in proxy and cannot be configured.
File location: Place proxy.ts at the same level as your app/ directory:
proxy.ts at project root--src-dir (or srcDir: true): src/proxy.ts (inside src/, alongside app/)If you place proxy.ts in the wrong location, Next.js will silently ignore it and no request interception will occur.
Constraints:
skipMiddlewareUrlNormalize → skipProxyUrlNormalize.proxy.ts yet — keep using middleware.ts if self-hosting with OpenNext.// proxy.ts (or src/proxy.ts if using src directory)
import type { NextRequest } from 'next/server'
export function proxy(request: NextRequest) {
// Rewrite, redirect, set headers, etc.
}
export const config = { matcher: ['/dashboard/:path*'] }
Use the built-in upgrade command (available since 16.1.0):
pnpm next upgrade # or npm/yarn/bun equivalent
For versions before 16.1.0: npx @next/codemod@canary upgrade latest
If your AI coding assistant supports MCP, the Next.js DevTools MCP can automate upgrade and migration tasks.
Next.js 16.1 (December 2025, latest stable patch: 16.1.6) builds on 16.0 with developer experience improvements:
next dev restarts, delivering up to 14× faster startup on large projects. Enabled by default, no config needed. File system caching for next build is planned next.experimental.bundleAnalyzer: true in next.config.next dev --inspect — Debug your dev server without global NODE_OPTIONS=--inspect. Applies the inspector only to the relevant process.next upgrade command — New CLI command to simplify version upgrades: npx @next/codemod@canary upgrade latest.serverExternalPackages without extra config.node_modules footprint.Next.js 16+ uses React 19.2. These features are available in App Router applications:
useEffectEvent HookCreates a stable function that always accesses the latest props and state without triggering effect re-runs. Use when your effect needs to read a value but shouldn't re-run when that value changes:
'use client'
import { useEffect, useEffectEvent } from 'react'
function ChatRoom({ roomId, theme }: { roomId: string; theme: string }) {
const onConnected = useEffectEvent(() => {
showNotification(`Connected to ${roomId}`, theme) // reads latest theme
})
useEffect(() => {
const connection = createConnection(roomId)
connection.on('connected', onConnected)
connection.connect()
return () => connection.disconnect()
}, [roomId]) // theme is NOT a dependency — onConnected reads it via useEffectEvent
}
Common use cases: logging with current state, notifications using current theme, callbacks that need fresh values but aren't the trigger for the effect.
<Activity> ComponentPreserves component state when hiding and showing UI, without unmounting. Solves the classic tradeoff between unmounting (loses state) and CSS display:none (effects keep running):
'use client'
import { Activity, useState } from 'react'
function TabContainer() {
const [activeTab, setActiveTab] = useState('inbox')
return (
<div>
<nav>
<button onClick={() => setActiveTab('inbox')}>Inbox</button>
<button onClick={() => setActiveTab('drafts')}>Drafts</button>
</nav>
<Activity mode={activeTab === 'inbox' ? 'visible' : 'hidden'}>
<InboxPanel />
</Activity>
<Activity mode={activeTab === 'drafts' ? 'visible' : 'hidden'}>
<DraftsPanel />
</Activity>
</div>
)
}
Use for: tabbed interfaces, modals, sidebars, background tasks — anywhere you need to maintain component state without keeping everything actively rendered. When mode="hidden", effects are suspended (not running in the background).
React 19.2 supports the browser View Transitions API for animating elements across navigations. Next.js 16 has built-in support — elements can animate between route changes without manual transition logic.
Key change: useId now generates IDs with _r_ prefix (instead of :r:) to be valid for view-transition-name and XML 1.0 names.
Next.js 16 deduplicates shared layouts during prefetching. When multiple <Link> components point to routes with a shared layout, the layout is downloaded once instead of separately for each link.
Impact: A page with 50 product links that share a layout downloads ~198KB instead of ~2.4MB — a 92% reduction in prefetch network transfer.
Combined with incremental prefetching, Next.js only fetches route segments not already in cache, cancels prefetch requests when links leave the viewport, re-prefetches on hover or viewport re-entry, and re-prefetches when data is invalidated.
next experimental-analyze)Built-in bundle analyzer that works with Turbopack (available since Next.js 16.1):
# Analyze and serve results in browser
next experimental-analyze --serve
# Analyze with custom port
next experimental-analyze --serve --port 4001
# Write analysis to .next/diagnostics/analyze (no server)
next experimental-analyze
Features:
Save output for comparison: cp -r .next/diagnostics/analyze ./analyze-before-refactor
Legacy: For projects not using Turbopack, use @next/bundle-analyzer with ANALYZE=true npm run build.
Next.js 16.2 is currently in canary (latest: 16.2.0-canary.84, March 2026). Key areas in development:
next build — Extending the stable next dev FS cache to production builds for faster CI.proxy.ts (the Node.js-runtime replacement for middleware.ts introduced in 16.0). The proxy API is stabilizing with improved request context and streaming support.Note: Canary releases are not recommended for production. Track progress at the Next.js Changelog or GitHub Releases.
Next.js 16 includes Next.js DevTools MCP, a Model Context Protocol integration for AI-assisted debugging. It enables AI agents to diagnose issues, explain behavior, and suggest fixes within your development workflow. If your AI coding assistant supports MCP, DevTools MCP can also automate upgrade and migration tasks.
cookies(), headers(), params, searchParams are all async — must await themmiddleware.ts → proxy.ts, runs on Node.js only (Edge not supported)experimental.turbopack to turbopack in next.configuseRef() Requires an Initial ValueReact 19 strict mode enforces that useRef() must be called with an explicit initial value. Omitting it causes a type error or runtime warning:
// WRONG — React 19 strict mode complains
const ref = useRef() // ❌ missing initial value
const ref = useRef<HTMLDivElement>() // ❌ still missing
// CORRECT
const ref = useRef<HTMLDivElement>(null) // ✅
const ref = useRef(0) // ✅
This affects all useRef calls in client components. The fix is always to pass an explicit initial value (usually null for DOM refs).
Multiple vulnerabilities affect all Next.js App Router applications (13.4+, 14.x, 15.x, 16.x). Upgrade immediately.
A deserialization vulnerability in the React Server Components (RSC) "Flight" protocol allows unauthenticated remote code execution via crafted HTTP requests. Near-100% exploit reliability against default configurations. Actively exploited in the wild. No workaround — upgrade is required. Rotate all application secrets after patching.
Specially crafted HTTP requests cause the server process to hang indefinitely, consuming CPU and blocking legitimate users. No authentication required, low attack complexity.
Malformed HTTP requests can trick Server Actions into returning their compiled source code instead of the expected response. Environment variables are not exposed, but any hardcoded secrets in Server Action code can leak.
Disclosed January 26, 2026. The original DoS fix for CVE-2025-55184 was incomplete — additional vectors allow specially crafted HTTP requests to Server Function endpoints to crash the server via out-of-memory exceptions or excessive CPU usage. No authentication required.
An attacker can bypass middleware-based authorization by sending a crafted x-middleware-subrequest header, skipping all middleware logic. This affects any Next.js application that relies on middleware.ts (or proxy.ts in 16+) as the sole authorization gate. Patched in Next.js 14.2.25, 15.2.3, and all 16.x releases.
Mitigation: Never rely on middleware/proxy as the only auth layer. Always re-validate authorization in Server Components, Server Actions, or Route Handlers. If you cannot patch immediately, block x-middleware-subrequest at your reverse proxy or WAF.
| Release Line | Minimum Safe Version (all CVEs) |
|---|---|
| 14.x | next@14.2.35 |
| 15.0.x | next@15.0.5 |
| 15.1.x | next@15.1.9 |
| 15.2.x | next@15.2.6 |
| 15.3.x | next@15.3.6 |
| 15.4.x | next@15.4.8 |
| 15.5.x | next@15.5.7 |
| 16.0.x | next@16.0.11 |
| 16.1.x | next@16.1.5 |
Upgrade React to at least 19.0.1 / 19.1.2 / 19.2.1 for the RCE fix (CVE-2025-55182), and 19.2.4+ to fully address all DoS vectors (CVE-2025-55184, CVE-2025-67779, CVE-2026-23864).
# Upgrade to latest patched versions
npm install next@latest react@latest react-dom@latest
Vercel deployed WAF rules automatically for hosted projects, but WAF is defense-in-depth, not a substitute for patching.
| Strategy | When to Use |
|---|---|
SSG (generateStaticParams) | Content rarely changes, maximum performance |
ISR (revalidate: N) | Content changes periodically, acceptable staleness |
| SSR (Server Components) | Per-request fresh data, personalized content |
Cache Components ('use cache') | Mix static shell with dynamic parts |
| Client Components | Interactive UI, browser APIs needed |
| Streaming (Suspense) | Show content progressively as data loads |
Choosing a rendering strategy?
├─ Content changes less than once per day?
│ ├─ Same for all users? → SSG (`generateStaticParams`)
│ └─ Personalized? → SSG shell + client fetch for personalized parts
│
├─ Content changes frequently but can be slightly stale?
│ ├─ Revalidate on schedule? → ISR with `revalidate: N` seconds
│ └─ Revalidate on demand? → `revalidateTag()` or `revalidatePath()`
│
├─ Content must be fresh on every request?
│ ├─ Cacheable per-request? → Cache Components (`'use cache'` + `cacheLife`)
│ ├─ Personalized per-user? → SSR with Streaming (Suspense boundaries)
│ └─ Real-time? → Client-side with SWR/React Query + SSR for initial load
│
└─ Mostly static with one dynamic section?
└─ Partial Prerendering: static shell + Suspense for dynamic island
| Data Type | Strategy | Implementation |
|---|---|---|
| Static assets (JS, CSS, images) | Immutable cache | Automatic with Vercel (hashed filenames) |
| API responses (shared) | Cache Components | 'use cache' + cacheLife('hours') |
| API responses (per-user) | No cache or short TTL | cacheLife({ revalidate: 60 }) with user-scoped key |
| Configuration data | Edge Config | @vercel/edge-config (< 5ms reads) |
| Database queries | ISR + on-demand | revalidateTag('products') on write |
| Full pages | SSG / ISR | generateStaticParams + revalidate |
| Search results | Client-side + SWR | useSWR with stale-while-revalidate |
// BEFORE: Unoptimized, causes LCP & CLS issues
<img src="/hero.jpg" />
// AFTER: Optimized with next/image
import Image from 'next/image';
<Image src="/hero.jpg" width={1200} height={600} priority alt="Hero" />
// BEFORE: External font causes CLS
<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
// AFTER: Zero-CLS with next/font
import { Inter } from 'next/font/google';
const inter = Inter({ subsets: ['latin'] });
// BEFORE: Re-fetches on every request
async function ProductList() {
const products = await db.query('SELECT * FROM products');
return <ul>{products.map(p => <li key={p.id}>{p.name}</li>)}</ul>;
}
// AFTER: Cached with automatic revalidation
'use cache';
import { cacheLife } from 'next/cache';
async function ProductList() {
cacheLife('hours');
const products = await db.query('SELECT * FROM products');
return <ul>{products.map(p => <li key={p.id}>{p.name}</li>)}</ul>;
}
// Instant feedback while Server Action processes
'use client';
import { useOptimistic } from 'react';
function LikeButton({ count, onLike }) {
const [optimisticCount, addOptimistic] = useOptimistic(count);
return (
<button onClick={() => { addOptimistic(count + 1); onLike(); }}>
{optimisticCount} likes
</button>
);
}
Next.js supports file-based OG image generation via opengraph-image.tsx and twitter-image.tsx special files. These use @vercel/og (built on Satori) to render JSX to images at the Edge runtime.
Place an opengraph-image.tsx (or twitter-image.tsx) in any route segment to auto-generate social images for that route:
// app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from 'next/og'
export const runtime = 'edge'
export const alt = 'Blog post'
export const size = { width: 1200, height: 630 }
export const contentType = 'image/png'
export default async function Image({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
const post = await fetch(`https://api.example.com/posts/${slug}`).then(r => r.json())
return new ImageResponse(
(
<div
style={{
fontSize: 48,
background: 'linear-gradient(to bottom, #000, #111)',
'',
'%',
'%',
'',
'',
'',
,
}}
>
{post.title}
),
{ ...size }
)
}
ImageResponse — Import from next/og (re-exports @vercel/og). Renders JSX to PNG/SVG images.runtime = 'edge' explicitly for clarity.alt, size, and contentType configure the generated <meta> tags automatically.style objects (no Tailwind). display: 'flex' is required on containers.fetch and pass to ImageResponse options: { fonts: [{ name, data, style, weight }] }.twitter-image.tsx exists, opengraph-image.tsx is used for Twitter cards too.| Approach | When |
|---|---|
opengraph-image.tsx file | Dynamic per-route OG images with data fetching |
Static opengraph-image.png file | Same image for every page in a segment |
generateMetadata with openGraph.images | Point to an external image URL |
vercel dev for local development with Vercel featuresnext/image (automatic on Vercel)next/font (automatic on Vercel)// Parallel data fetching
const [users, posts] = await Promise.all([
getUsers(),
getPosts(),
])
import { Suspense } from 'react'
export default function Page() {
return (
<div>
<h1>Dashboard</h1>
<Suspense fallback={<Skeleton />}>
<SlowDataComponent />
</Suspense>
</div>
)
}
// app/dashboard/error.tsx
'use client'
export default function Error({ error, reset }: {
error: Error & { digest?: string }
reset: () => void
}) {
return (
<div>
<h2>Something went wrong</h2>
<button onClick={() => reset()}>Try again</button>
</div>
)
}