# Scaffold Nextjs App > Scaffold a new Next.js application with App Router, TypeScript, and modern defaults. Covers project creation, directory structure, routing setup, and initial configuration. Use when starting a new web application project, creating a React-based frontend with server-side rendering, building a full-stack application with API routes, or setting up a TypeScript web project from scratch. - Skill: `pjt222/scaffold-nextjs-app-7` (Agent Skill) - Install (CLI): `npx skillmds@latest add pjt222/scaffold-nextjs-app-7` - Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/scaffold-nextjs-app-7/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - License: MIT - Author: pjt222 (https://skillmd.com/u/pjt222) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/pjt222/scaffold-nextjs-app-7 --- # 構建 Next.js 應用腳手架 以 App Router、TypeScript 與生產就緒之預設建立 Next.js 應用。 ## 適用時機 - 新建網頁應用項目 - 建立含伺服器端渲染之 React 前端 - 建構含 API 路由之全端應用 - 從頭設置 TypeScript 網頁項目 ## 輸入 - **必要**：應用名 - **必要**：套件管理器偏好（npm、yarn、pnpm） - **選擇性**：是否含 Tailwind CSS（預設：是） - **選擇性**：是否含 ESLint（預設：是） - **選擇性**：src/ 目錄結構（預設：是） ## 步驟 ### 步驟一：建立項目 ```bash npx create-next-app@latest my-app \ --typescript \ --tailwind \ --eslint \ --app \ --src-dir \ --import-alias "@/*" ``` 回應提示或用旗標非互動式設定所有選項。 **預期：** 項目目錄已建立，所有依賴已安裝。 **失敗時：** 檢查 Node.js 版本（`node --version`，須 >= 18.17）。確保 `npx` 可用。若命令於提示處懸停，加入 `--use-npm` 旗標（或 `--use-pnpm`／`--use-yarn`）以跳過套件管理器提示。 ### 步驟二：驗證項目結構 ```text my-app/ ├── src/ │ ├── app/ │ │ ├── layout.tsx # Root layout │ │ ├── page.tsx # Home page │ │ ├── globals.css # Global styles │ │ └── favicon.ico │ └── lib/ # Shared utilities (create manually) ├── public/ # Static assets ├── next.config.ts # Next.js configuration ├── tailwind.config.ts # Tailwind configuration ├── tsconfig.json # TypeScript configuration ├── package.json └── .eslintrc.json ``` **預期：** 所有列出之目錄與文件皆存在。 **失敗時：** 若 `src/` 目錄缺失，未傳 `--src-dir` 旗標。重新執行 `create-next-app` 附該旗標，或手動將文件移入 `src/app/`。 ### 步驟三：配置 Next.js 依項目需求編輯 `next.config.ts`： ```typescript import type { NextConfig } from "next"; const nextConfig: NextConfig = { // Enable React strict mode reactStrictMode: true, // Image optimization domains images: { remotePatterns: [ { protocol: "https", hostname: "example.com", }, ], }, }; export default nextConfig; ``` **預期：** `next.config.ts` 儲存無 TypeScript 錯誤。 **失敗時：** 若文件用 `.js` 副檔名而非 `.ts`，重新命名之。確保 `NextConfig` 類型自 `"next"` 引入。 ### 步驟四：設置目錄慣例 建立常用目錄： ```bash mkdir -p src/app/api mkdir -p src/components mkdir -p src/lib mkdir -p src/types ``` **預期：** 四目錄皆於 `src/` 下建立。 **失敗時：** 若 `src/` 不存在，先建立之或調整路徑以符合項目結構（非 src 佈局於根用 `app/`）。 ### 步驟五：建立基底佈局 編輯 `src/app/layout.tsx`： ```tsx import type { Metadata } from "next"; import { Inter } from "next/font/google"; import "./globals.css"; const inter = Inter({ subsets: ["latin"] }); export const metadata: Metadata = { title: "My Application", description: "Application description", }; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {children} ); } ``` **預期：** 佈局以 Inter 字體渲染並包覆所有頁面。 **失敗時：** 若字體載入失敗，檢查網路存取。將 `Inter` 暫時換為系統字體後備。 ### 步驟六：加入範例 API 路由 建立 `src/app/api/health/route.ts`： ```typescript import { NextResponse } from "next/server"; export async function GET() { return NextResponse.json({ status: "ok", timestamp: new Date().toISOString() }); } ``` **預期：** 文件已建於 `src/app/api/health/route.ts`。 **失敗時：** 確保 `api/health/` 目錄存在。文件須匯出具名 HTTP 方法處理器（`GET`、`POST` 等），非預設匯出。 ### 步驟七：執行開發伺服器 ```bash cd my-app npm run dev ``` **預期：** 應用於 http://localhost:3000 運行。 **失敗時：** 檢查 Node.js 版本（>= 18.17）。若依賴缺失，執行 `npm install`。 ## 驗證 - [ ] `npm run dev` 無錯誤啟動 - [ ] 首頁於 localhost:3000 載入 - [ ] TypeScript 編譯成功 - [ ] Tailwind CSS 類別已套用 - [ ] API 路由於 /api/health 回應 - [ ] ESLint 無錯誤執行（`npm run lint`） ## 常見陷阱 - **Node.js 版本**：Next.js 需 Node.js >= 18.17。以 `node --version` 檢查。 - **連接埠衝突**：預設 3000 連接埠可能被佔。改用 `npm run dev -- -p 3001`。 - **引入別名混淆**：`@/*` 對應 `src/*`。勿與 node_modules 引入混淆。 - **Pages 對 App Router**：確保用 App Router（`src/app/`）非 Pages Router（`src/pages/`）。 ## 相關技能 - `setup-tailwind-typescript` - 詳細 Tailwind 與 TypeScript 配置 - `deploy-to-vercel` - 部署腳手架應用 - `configure-git-repository` - 版本控制設置