Communitygithub.com

ComeOnOliver/skillshub

使用正确的模式和独特的设计构建 Next.js 16 应用程序。适用于创建页面、布局、动态路由、从 Next.js 15 升级,或实现 proxy.ts。涵盖重大变更(async params/searchParams、Turbopack、cacheComponents)和前端美观性。不适用于构建非 React 或仅后端应用程序。

skillshub 是什么?

这是一个专注于 Next.js 16 应用程序开发的 AI 智能体技能。它提供了从项目初始化到生产部署的完整指导,特别强调了 Next.js 16 中的重大变更,例如 `params` 和 `searchParams` 必须作为 Promise 处理。该技能支持多种开发工具,如 Claude Code、Cursor 和 Codex,并集成了 `next-devtools-mcp` 服务器,用于运行时诊断和开发自动化。此外,它还涵盖了项目结构、服务器操作、API 路由和代理配置,帮助开发者避免常见错误并遵循最佳实践。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/aiskillstore/marketplace/asmayaseen/building-nextjs-apps

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Next.js 16 应用程序

使用独特的设计正确构建 Next.js 16 应用程序。

重大变更(Next.js 16)

1. params 和 searchParams 现在是 Promise

这是最常见的错误。

// 错误 - Next.js 15 模式(将失败)
export default function Page({ params }: { params: { id: string } }) {
  return <div>ID: {params.id}</div>
}

// 正确 - Next.js 16 模式
export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  return <div>ID: {id}</div>
}

2. 客户端组件需要使用 use() 钩子

"use client"
import { use } from "react"

export default function ClientPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = use(params)
  return <div>ID: {id}</div>
}

3. searchParams 也需要异步处理

export default async function Page({
  searchParams,
}: {
  searchParams: Promise<{ page?: string }>
}) {
  const { page } = await searchParams
  return <div>Page: {page ?? "1"}</div>
}

核心模式

项目设置

npx create-next-app@latest my-app --typescript --tailwind --eslint
cd my-app

# 添加 shadcn/ui
npx shadcn@latest init
npx shadcn@latest add button form dialog table sidebar

App Router 布局

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body className="min-h-screen">
        {children}
      </body>
    </html>
  )
}

动态路由

// app/tasks/[id]/page.tsx
export default async function TaskPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const task = await getTask(id)

  return (
    <main>
      <h1>{task.title}</h1>
    </main>
  )
}

服务器操作

// app/actions.ts
"use server"

import { revalidatePath } from "next/cache"

export async function createTask(formData: FormData) {
  const title = formData.get("title") as string

  await db.insert(tasks).values({ title })

  revalidatePath("/tasks")
}

// 在组件中使用
<form action={createTask}>
  <input name="title" />
  <button type="submit">创建</button>
</form>

API 路由

// app/api/tasks/route.ts
import { NextResponse } from "next/server"

export async function GET() {
  const tasks = await db.select().from(tasksTable)
  return NextResponse.json(tasks)
}

export async function POST(request: Request) {
  const body = await request.json()
  const task = await db.insert(tasksTable).values(body).returning()
  return NextResponse.json(task, { status: 201 })
}

中间件 → proxy.ts

// proxy.ts(替代 Next.js 16 中的 middleware.ts)
import { NextRequest } from "next/server"

export function proxy(request: NextRequest) {
  // 身份验证检查
  const token = request.cookies.get("token")
  if (!token && request.nextUrl.pathname.startsWith("/dashboard")) {
    return Response.redirect(new URL("/login", request.url))
  }
}

export const config = {
  matcher: ["/dashboard/:path*"],
}

数据获取

服务器组件(默认)

// 这段代码在服务器上运行 - 可以直接使用 async/await
async function TaskList() {
  const tasks = await fetch("https://api.example.com/tasks", {
    cache: "no-store", // SSR,或者
    // next: { revalidate: 60 } // ISR
  }).then(r => r.json())

  return (
    <ul>
      {tasks.map(task => <li key={task.id}>{task.title}</li>)}
    </ul>
  )
}

客户端组件

"use client"

import useSWR from "swr"

const fetcher = (url: string) => fetch(url).then(r => r.json())

export function ClientTaskList() {
  const { data, error, isLoading } = useSWR("/api/tasks", fetcher)

  if (isLoading) return <div>加载中...</div>
  if (error) return <div>加载任务出错</div>

  return (
    <ul>
      {data.map(task => <li key={task.id}>{task.title}</li>)}
    </ul>
  )
}

项目结构

app/
├── layout.tsx           # 根布局
├── page.tsx             # 首页
├── globals.css          # 全局样式
├── api/                 # API 路由
│   └── tasks/route.ts
├── tasks/
│   ├── page.tsx         # /tasks
│   └── [id]/page.tsx    # /tasks/:id
├── actions.ts           # 服务器操作
└── proxy.ts             # 请求代理(中间件)
components/
├── ui/                  # shadcn/ui 组件
└── task-list.tsx        # 应用程序组件
lib/
├── db.ts                # 数据库连接
└── utils.ts             # 工具函数

Next.js DevTools MCP

使用 next-devtools-mcp 服务器进行运行时诊断和开发自动化。

设置

claude mcp add next-devtools npx next-devtools-mcp@latest

或者在 settings.json 中:

{
  "mcpServers": {
    "next-devtools": {
      "type": "stdio",
      "command": "npx",
      "args": ["next-devtools-mcp@latest"]
    }
  }
}

可用工具

工具用途
init建立上下文,了解可用工具和最佳实践
nextjs_docs搜索和获取官方 Next.js 文档
browser_eval使用 Playwright 自动化浏览器测试
nextjs_index发现正在运行的 Next.js 开发服务器
nextjs_call在正在运行的开发服务器上执行 MCP 工具
upgrade_nextjs_16使用 codemods 自动升级
enable_cache_components为 Next.js 16 配置缓存组件

关键用例

1. 获取实时错误

"我的 Next.js 应用有哪些构建错误?"
"显示当前项目中的 TypeScript 错误"

2. 调试运行时问题

"检查开发服务器日志中的错误"
"仪表板页面发生了哪些运行时错误?"

3. 升级协助

"将此项目升级到 Next.js 16"
"为这个应用启用缓存组件"

4. 文档查询

"如何在 Next.js 16 中使用 Image 组件?"
"处理动态路由的正确方法是什么?"

Next.js 16 MCP 端点

Next.js 16+ 在 http://localhost:3000/_next/mcp(或您的开发服务器端口)暴露了内置的 MCP 端点。devtools MCP 会自动发现并连接到正在运行的服务器。


验证

运行:python3 scripts/verify.py

预期结果:✓ building-nextjs-apps skill ready

如果验证失败

  1. 检查:references/ 文件夹中是否有 nextjs-16-patterns.md
  2. 如果仍然失败,请停止并报告

相关技能

  • styling-with-shadcn - Next.js 应用的 UI 组件
  • fetching-library-docs - 最新的 Next.js 文档:--library-id /vercel/next.js --topic routing
  • configuring-better-auth - Next.js 应用的 OAuth/SSO

参考资料

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Next.js 16+ uses App Router with Server Components by default. Client Components are only used when interactivity is needed (hooks, event handlers, browser APIs).

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

相关技能