建立 Next.js 專案

本章節將帶你用 shadcn create 建立專案，並設定好所有必要的 MCP。

Step 1：安裝 MCP

在建立專案之前，先安裝所有需要的 MCP：

shadcn MCP

查詢 shadcn/ui 元件文件、範例、props：

bash

npx shadcn@latest mcp init --client claude

Context7 MCP

取得最新的套件文件（Next.js、React、Tailwind 等）：

bash

claude mcp add context7 -- npx -y @upstash/context7-mcp@latest

Next.js DevTools MCP

Next.js 開發工具，取得最佳實踐和錯誤偵測：

bash

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

Playwright MCP

瀏覽器自動化，用於測試和截圖（Microsoft 官方）：

bash

claude mcp add playwright -- npx @playwright/mcp@latest

驗證安裝

bash

claude
/mcp

應該看到所有 MCP 都是 connected 狀態。

Step 2：使用 shadcn create

方法 1：線上設計器（推薦）

前往 ui.shadcn.com/create
選擇你喜歡的設計：
- Style：Default / New York
- Base Color：Zinc / Slate / Stone / Gray / Neutral
- Radius：0 / 0.3 / 0.5 / 0.75 / 1.0
預覽各種元件的樣式
點擊右上角 Create Project
複製產生的指令：

bash

npx shadcn@latest init -c https://ui.shadcn.com/r/[your-config-id]

在終端機執行指令

方法 2：CLI 直接建立

如果不需要自訂設計：

bash

# 建立新專案
npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"

# 進入專案
cd my-app

# 初始化 shadcn
npx shadcn@latest init

選擇選項：

✔ Which style would you like to use? → New York
✔ Which color would you like to use as the base color? → Neutral
✔ Would you like to use CSS variables for theming? → Yes

Step 3：安裝所有 shadcn 元件

一次安裝全部

bash

npx shadcn@latest add --all

這會安裝所有基礎元件，包括：

Button、Card、Input、Form
Dialog、Sheet、Drawer
Table、Tabs、Accordion
Avatar、Badge、Separator
等等...

從 Registry 安裝進階元件

前往 ui.shadcn.com/docs/directory

找到需要的元件，例如：

bash

# 日期選擇器
npx shadcn@latest add "https://ui.shadcn.com/r/date-picker"

# 地圖元件
npx shadcn@latest add "https://ui.shadcn.com/r/map"

# 富文本編輯器
npx shadcn@latest add "https://ui.shadcn.com/r/editor"

# 圖表
npx shadcn@latest add "https://ui.shadcn.com/r/charts"

用 Claude + shadcn MCP 找元件

我需要一個可以選擇日期範圍的元件，幫我找適合的 shadcn 元件

Claude 會用 shadcn MCP 查詢並告訴你：

有哪些相關元件
如何安裝
使用範例

Step 4：設定 Package Manager

使用 pnpm（推薦）

bash

# 刪除 node_modules 和 lock file
rm -rf node_modules package-lock.json

# 使用 pnpm 重新安裝
pnpm install

使用 bun

bash

# 刪除 node_modules 和 lock file
rm -rf node_modules package-lock.json

# 使用 bun 重新安裝
bun install

Step 5：建立 CLAUDE.md

在專案根目錄建立 CLAUDE.md：

markdown

# CLAUDE.md

## 專案資訊

這是一個 [專案名稱]，使用以下技術棧：

- **框架：** Next.js 16 + App Router
- **UI：** shadcn/ui + Tailwind CSS v4
- **語言：** TypeScript (strict mode)
- **後端：** Supabase
- **Package Manager：** pnpm

## 目錄結構

├── app/ # Next.js App Router ├── components/ │ ├── ui/ # shadcn/ui 元件 │ └── features/ # 功能元件 ├── lib/ │ ├── supabase/ # Supabase client │ └── utils.ts # 工具函數 ├── types/ # TypeScript 型別 └── supabase/ # Supabase migrations


## 開發 SOP

每個 feature 完成後必須執行：

1. **Review**
   ```bash
   /review

Test
bash
```
pnpm test
```
Lint
bash
```
pnpm lint
```
Build
bash
```
pnpm build
```

Commit（只在以上都通過後）

bash

git add .
git commit -m "feat: [功能名稱]"

開發規範

TypeScript

使用 strict mode
不使用 any 類型
所有 props 都要定義型別

React / Next.js

優先使用 Server Components
有用到 hooks 或事件的元件必須加 "use client"
使用 Server Actions 處理表單

shadcn/ui

從 @/components/ui 匯入元件
不要直接從 @radix-ui 匯入
使用 cn() 函數合併 class names

Supabase

使用 @/lib/supabase/server 在 Server Components
使用 @/lib/supabase/client 在 Client Components
所有 table 都要啟用 RLS

常見錯誤提醒

不要直接 import from @radix-ui
有 hooks/事件的元件要加 "use client"
Server Actions 要加 "use server"
環境變數要加 NEXT_PUBLIC_ 前綴（前端用）


## Step 6：啟動 Claude Code

```bash
claude

測試 MCP 是否正常

/mcp

測試 shadcn MCP

幫我查詢 shadcn Button 元件的所有 variants

測試 Context7

use context7 - Next.js 16 的 Server Actions 怎麼用

Step 7：開始開發

第一個 Prompt

請幫我建立首頁：

1. 頂部導航列（Logo + 導航連結）
2. Hero 區塊（標題 + 描述 + CTA 按鈕）
3. 功能特色區塊（3-4 個特色卡片）
4. 頁尾

使用 shadcn/ui 元件
參考 CLAUDE.md 的規範

使用 Plan Mode

對於複雜功能，先規劃：

bash

/plan 實作使用者認證系統

使用 /ralph-loop

讓 Claude 自主迭代開發：

bash

/ralph-loop

# 然後描述功能
實作行程管理功能：
1. 行程列表頁面
2. 行程詳情頁面
3. 新增行程表單
4. 編輯行程功能

遵循 CLAUDE.md 的 SOP

常見問題

shadcn 元件樣式怪怪的

檢查 app/globals.css 有沒有 Tailwind directives：

css

@tailwind base;
@tailwind components;
@tailwind utilities;

"use client" 錯誤

有用到 hooks 或事件的元件要加：

typescript

"use client";

import { useState } from 'react';
// ...

MCP 無法連接

bash

# 重新啟動 Claude Code
exit
claude

# 檢查 MCP 狀態
/mcp

找不到元件

確認已安裝：

bash

# 查看已安裝的元件
ls components/ui/

# 安裝缺少的元件
npx shadcn@latest add [component-name]

下一步

整合 Supabase - 加入後端
部署到 Vercel - 上線

建立 Next.js 專案 ​

Step 1：安裝 MCP ​

shadcn MCP ​

Context7 MCP ​

Next.js DevTools MCP ​

Playwright MCP ​

驗證安裝 ​

Step 2：使用 shadcn create ​

方法 1：線上設計器（推薦） ​

方法 2：CLI 直接建立 ​

Step 3：安裝所有 shadcn 元件 ​

一次安裝全部 ​

從 Registry 安裝進階元件 ​

用 Claude + shadcn MCP 找元件 ​

Step 4：設定 Package Manager ​

使用 pnpm（推薦） ​

使用 bun ​

Step 5：建立 CLAUDE.md ​

開發規範 ​

TypeScript ​

React / Next.js ​

shadcn/ui ​

Supabase ​

常見錯誤提醒 ​

測試 MCP 是否正常 ​

測試 shadcn MCP ​

測試 Context7 ​

Step 7：開始開發 ​

第一個 Prompt ​

使用 Plan Mode ​

使用 /ralph-loop ​

常見問題 ​

shadcn 元件樣式怪怪的 ​

"use client" 錯誤 ​

MCP 無法連接 ​

找不到元件 ​

下一步 ​

建立 Next.js 專案

Step 1：安裝 MCP

shadcn MCP

Context7 MCP

Next.js DevTools MCP

Playwright MCP

驗證安裝

Step 2：使用 shadcn create

方法 1：線上設計器（推薦）

方法 2：CLI 直接建立

Step 3：安裝所有 shadcn 元件

一次安裝全部

從 Registry 安裝進階元件

用 Claude + shadcn MCP 找元件

Step 4：設定 Package Manager

使用 pnpm（推薦）

使用 bun

Step 5：建立 CLAUDE.md

開發規範

TypeScript

React / Next.js

shadcn/ui

Supabase

常見錯誤提醒

測試 MCP 是否正常

測試 shadcn MCP

測試 Context7

Step 7：開始開發

第一個 Prompt

使用 Plan Mode

使用 /ralph-loop

常見問題

shadcn 元件樣式怪怪的

"use client" 錯誤

MCP 無法連接

找不到元件

下一步