Communitygithub.com

ComeOnOliver/skillshub

使用正確的模式和獨特的設計來建構 Next.js 16 應用程式。適用於建立頁面、佈局、動態路由、從 Next.js 15 升級,或實作 proxy.ts。涵蓋重大變更(非同步 params/searchParams、Turbopack、cacheComponents)以及前端美學。不適用於非 React 或僅後端應用程式。

skillshub 是什麼?

這個技能旨在幫助開發者與 AI 代理(如 Claude Code、Cursor 或 Codex)正確且高效地建構 Next.js 16 應用程式。它提供了關於 Next.js 16 主要重大變更的全面指南,其中最關鍵的是 `params` 和 `searchParams` 現在都必須作為 Promise 處理,這與 Next.js 15 的模式有顯著不同。該技能涵蓋了完整的開發流程,從專案初始化、App Router 佈局、動態路由、伺服器操作(Server Actions)到 API 路由的實作,並強調在前端使用 shadcn/ui 來打造具區別性的設計。此外,它還詳細說明了如何設定和使用 next-devtools-mcp 進行執行時期診斷與開發自動化,並指導如何升級到 Next.js 16 以及啟用快取元件(Cache Components)。總結來說,此技能讓使用者能夠透過清晰的程式碼範例和最佳實務,快速建立符合最新框架特性的 Next.js 16 應用程式。

相容平台✓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() Hook

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

伺服器操作(Server Actions)

// 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">Create</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 })
}

Middleware → 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>Loading...</div>
  if (error) return <div>Error loading tasks</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             # 請求代理(middleware)
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

相關技能