Communitygithub.com

ComeOnOliver/skillshub

用於處理 Next.js App Router 任務——在 /app/ 中建立頁面、設定動態路由([id]/page.tsx)、實作巢狀佈局/模板(layout.tsx)、最佳化伺服器/客戶端元件,或建置 ERP 角色型頁面(管理員/教師/學生儀表板)。自動用於所有 /app/ 目錄操作、動態路由及 App Router 專屬功能。

skillshub 是什麼?

此技能專為 Next.js App Router 開發提供專業指導,涵蓋頁面建立、動態路由、巢狀佈局、伺服器/客戶端元件最佳化以及 ERP 角色型儀表板。它遵循伺服器元件優先原則,預設不使用 'use client' 指令,並利用 async/await 進行資料擷取,同時以 Suspense 邊界處理載入狀態。技能提供具體的程式碼範本,包括頁面(page.tsx)、動態路由([id]/page.tsx)、平行路由(@folder)、佈局(layout.tsx)與模板(template.tsx),並明確區分伺服器元件與客戶端元件的使用場景。此外,也整合了 shadcn/ui 元件庫以及錯誤邊界(error.tsx)與載入狀態(loading.tsx)的處理,適合在各主流 AI 代理平台(如 Claude Code、Cursor、Codex)上使用,協助開發者快速產出結構清晰、效能量佳且符合無障礙標準的 Next.js 應用程式。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/aiskillstore/marketplace/awais68/frontend-nextjs-app-router

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Next.js App Router 專家

概述

針對 Next.js App Router 開發的專業指南,包括頁面建立、動態路由、巢狀佈局、伺服器/客戶端元件最佳化,以及 ERP 角色型儀表板。

核心能力

1. 頁面建立(/app/.../page.tsx)

規則:

  • 預設使用伺服器元件(不使用 'use client' 指令)
  • 使用 fetch() 或 ORM 查詢直接進行非同步資料擷取
  • 初始資料載入不使用 useEffect
  • 使用 Suspense 邊界處理載入狀態
  • 透過 generateMetadata() 設定 SEO 元資料

範本:

// app/dashboard/page.tsx
import { Suspense } from 'react';
import { TaskList } from '@/components/TaskList';
import { TaskListSkeleton } from '@/components/TaskListSkeleton';

export const metadata = {
  title: '儀表板',
  description: '您的任務管理儀表板',
};

export default async function DashboardPage() {
  const tasks = await fetchTasks();

  return (
    <main className="p-4">
      <h1>儀表板</h1>
      <Suspense fallback={<TaskListSkeleton />}>
        <TaskList initialTasks={tasks} />
      </Suspense>
    </main>
  );
}

2. 動態路由([slug]/page.tsx)

使用時機:

  • 學生個人檔案:app/students/[studentId]/page.tsx
  • 任務詳細資料:app/tasks/[taskId]/page.tsx
  • 課程頁面:app/courses/[courseId]/page.tsx

規則:

  • 從 params 屬性(唯讀)中提取參數
  • 使用 generateMetadata() 進行 SEO
  • 使用 not-found.tsx 處理 404

範本:

// app/students/[studentId]/page.tsx
import { notFound } from 'next/navigation';

type Params = Promise<{ studentId: string }>;

export async function generateMetadata({ params }: { params: Params }) {
  const { studentId } = await params;
  const student = await getStudent(studentId);

  if (!student) return { title: '找不到學生' };

  return {
    title: `${student.name} - 學生個人檔案`,
  };
}

export default async function StudentProfile({ params }: { params: Params }) {
  const { studentId } = await params;
  const student = await getStudent(studentId);

  if (!student) notFound();

  return <StudentProfileView student={student} />;
}

3. 平行路由(@folder)

使用時機:

  • 儀表板變體:app/dashboard@(admin|teacher)/page.tsx
  • 分割佈局:app/settings@(user|organization)/layout.tsx

範本:

// app/dashboard/@admin/page.tsx - 管理員儀表板
export default function AdminDashboard() {
  return <AdminPanel />;
}

// app/dashboard/@teacher/page.tsx - 教師儀表板
export default function TeacherDashboard() {
  return <TeacherPanel />;
}

4. 佈局與模板

根佈局(app/layout.tsx):

import { Providers } from '@/components/Providers';
import './globals.css';

export const metadata = {
  title: 'Todo Evolution',
  description: '教育用任務管理',
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh-TW">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

巢狀佈局(app/dashboard/layout.tsx):

import { DashboardNav } from '@/components/DashboardNav';

export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="flex min-h-screen">
      <DashboardNav />
      <main className="flex-1 p-6">{children}</main>
    </div>
  );
}

模板(app/tasks/template.tsx):

// 導航時重新執行,保留表單狀態
export default function TasksTemplate({ children }: { children: React.ReactNode }) {
  return (
    <div className="bg-gray-50 min-h-screen">
      <header className="bg-white shadow">
        <h1>任務</h1>
      </header>
      {children}
    </div>
  );
}

5. 伺服器元件 vs 客戶端元件

伺服器元件用於:

  • 資料擷取
  • 直接資料庫查詢
  • 靜態內容
  • 僅限伺服器的操作

客戶端元件('use client')用於:

  • 瀏覽器 API(window、localStorage)
  • 事件處理器(onClick、onSubmit)
  • React 鉤子(useState、useEffect)
  • 狀態管理(Zustand、Redux)
  • 互動性
// 伺服器元件(預設)
export default async function TaskList() {
  const tasks = await fetchTasks(); // 直接資料庫查詢
  return <div>{tasks.map(/* ... */)}</div>;
}

// 客戶端元件
'use client';
import { useTaskStore } from '@/store/tasks';

export function TaskFilter() {
  const { filter, setFilter } = useTaskStore();
  return <button onClick={() => setFilter('all')}>所有任務</button>;
}

6. ERP 角色型頁面

角色守衛:

// app/admin/page.tsx
import { requireRole } from '@/lib/auth';
import { redirect } from 'next/navigation';

export default async function AdminPage() {
  const session = await getSession();

  if (session?.role !== 'admin') {
    redirect('/unauthorized');
  }

  return <AdminDashboard />;
}

KPI 儀表板(Recharts):

'use client';
import { BarChart, Bar, XAxis, YAxis, Tooltip } from 'recharts';

export function TaskKPIChart({ data }: { data: TaskStats[] }) {
  return (
    <BarChart width={600} height={300} data={data}>
      <XAxis dataKey="date" />
      <YAxis />
      <Tooltip />
      <Bar dataKey="completed" fill="#22c55e" />
    </BarChart>
  );
}

7. 錯誤與載入狀態

錯誤邊界(error.tsx):

'use client';
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div>
      <h2>發生錯誤!</h2>
      <button onClick={reset}>重試</button>
    </div>
  );
}

載入狀態(loading.tsx):

export default function Loading() {
  return <div className="animate-pulse">載入中...</div>;
}

// 或搭配 Suspense:
export default async function Page() {
  return (
    <Suspense fallback={<Loading />}>
      <Content />
    </Suspense>
  );
}

8. shadcn/ui 整合

安裝:

npx shadcn@latest add button card input dialog

在伺服器元件中使用:

import { Button } from '@/components/ui/button';
import { Card, CardContent, CardHeader } from '@/components/ui/card';

export default async function TaskPage() {
  const tasks = await getTasks();

  return (
    <Card>
      <CardHeader>任務</CardHeader>
      <CardContent>
        {tasks.map(task => (
          <div key={task.id}>{task.title}</div>
        ))}
      </CardContent>
    </Card>
  );
}

工作流程決策樹

使用者請求 → 分析 → 實作路徑

  1. 「建立儀表板/管理員頁面」 → 使用 page.tsx 的伺服器元件 → 非同步資料擷取 → 如需導航則加入 layout.tsx

  2. 「動態學生個人檔案」 → 建立 [studentId]/page.tsx → 提取參數 → 加入 generateMetadata() → 如有需要建立 not-found.tsx

  3. 「加入共用佈局」 → 在目標資料夾中建立 layout.tsx → 如有需要以 Provider 包裹 → 保留 children 渲染

  4. 「加入表單」 → 使用 'use client' 元件 → 使用 useState 處理表單資料 → 使用伺服器動作或 API 路由提交

  5. 「KPI 圖表/分析」 → 使用 'use client' 搭配 Recharts → 父層使用伺服器元件並擷取資料 → 將資料作為 props 傳遞

品質檢查清單

在標記任務完成前:

  • TypeScript 嚴格模式已啟用
  • 預設使用伺服器元件
  • 僅在必要時使用 'use client'
  • 使用 generateMetadata() 進行 SEO
  • 為非同步資料使用 Suspense 邊界
  • 在需要的地方設有錯誤邊界(error.tsx)
  • 無水合不匹配
  • 效能最佳化(無阻塞渲染)
  • 行動裝置優先的響應式設計
  • 無障礙(ARIA 標籤、鍵盤導航)

常見模式

模式 1:伺服器元件與客戶端元件混合

// 伺服器元件
export default async function Page() {
  const tasks = await fetchTasks();
  return <TaskList tasks={tasks} />; // 客戶端元件提供互動性
}

'use client';
function TaskList({ tasks }: { tasks: Task[] }) {
  const [filter, setFilter] = useState('all');
  const filtered = tasks.filter(/* ... */);
  return <div>{filtered.map(/* ... */)}</div>;
}

模式 2:用於組織的路由群組

app/
  (marketing)/     # 群組:無 URL 區段
    about/page.tsx
    contact/page.tsx
  (dashboard)/      # 群組:無 URL 區段
    layout.tsx
    page.tsx

模式 3:API 路由(路由處理器)

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

export async function GET() {
  const tasks = await db.query.tasks.findMany();
  return NextResponse.json(tasks);
}

export async function POST(request: Request) {
  const body = await request.json();
  const task = await createTask(body);
  return NextResponse.json(task, { status: 201 });
}

觸發範例

  • 「建立儀表板頁面」→ 產生 app/dashboard/page.tsx 並使用伺服器元件
  • 「動態學生個人檔案路由」→ app/students/[studentId]/page.tsx 搭配 params 與 metadata
  • 「加入共用佈局」→ app/dashboard/layout.tsx 並搭配 children
  • 「包含圖表的管理員面板」→ 伺服器元件 + 客戶端圖表元件
  • 「建立登入頁面」→ 'use client' 表單元件 + API 路由
  • 「自訂 404 頁面」→ app/not-found.tsx
  • 「處理錯誤」→ app/dashboard/error.tsx

參考資料

進階模式請參閱 references/app-router-patterns.md,路由處理器範例請參閱 references/api-routes.md。

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

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

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

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

相關技能