入門指南

建立新專案

我們推薦使用 pnpm 作為套件管理工具，因為它比 npm 或 yarn 更快速高效。如果尚未安裝 pnpm，可以執行以下指令進行全域安裝：

npm install -g pnpm

要建立 Next.js 應用程式，請開啟終端機，cd 進入您想存放專案的目錄，然後執行以下指令：

npx create-next-app@latest nextjs-dashboard --example "https://github.com/vercel/next-learn/tree/main/dashboard/starter-example" --use-pnpm

此指令使用了 create-next-app，這是一個能為您自動設定 Next.js 應用程式的命令列介面 (CLI) 工具。在上述指令中，您還使用了 --example 旗標搭配本課程的起始範例。

探索專案結構

與從零開始編寫程式碼的教學不同，本課程的大部分程式碼已為您準備好。這更貼近實際開發情境，您很可能會需要處理現有的程式碼庫。

我們的目標是讓您專注於學習 Next.js 的主要功能，而不必編寫「所有」應用程式程式碼。

安裝完成後，請在程式碼編輯器中開啟專案並導航至 nextjs-dashboard 目錄：

cd nextjs-dashboard

讓我們花些時間探索這個專案。

目錄結構

您會注意到專案具有以下目錄結構：

• /app：包含應用程式的所有路由、元件和邏輯，這將是您主要工作的目錄。
• /app/lib：包含應用程式中使用的函式，例如可重複使用的工具函式和資料獲取函式。
• /app/ui：包含應用程式的所有 UI 元件，例如卡片、表格和表單。為了節省時間，我們已為您預先設計了這些元件的樣式。
• /public：包含應用程式的所有靜態資源，例如圖片。
• 設定檔案：您還會在專案根目錄看到如 next.config.ts 等設定檔。這些檔案大多是在使用 create-next-app 建立新專案時自動生成並預先設定的。在本課程中您無需修改這些檔案。

請隨意瀏覽這些目錄，如果還不完全理解程式碼的作用也無需擔心。

預留位置資料

在構建使用者介面時，擁有預留位置資料會很有幫助。如果資料庫或 API 尚未就緒，您可以：

• 使用 JSON 格式或 JavaScript 物件形式的預留位置資料。
• 使用第三方服務如 mockAPI。

在本專案中，我們已在 app/lib/placeholder-data.ts 中提供了一些預留位置資料。檔案中的每個 JavaScript 物件代表資料庫中的一個表格。例如，發票表格的資料如下：

const invoices = [
  {
    customer_id: customers[0].id,
    amount: 15795,
    status: 'pending',
    date: '2022-12-06',
  },
  {
    customer_id: customers[1].id,
    amount: 20348,
    status: 'pending',
    date: '2022-11-14',
  },
  // ...
];

在設定資料庫章節中，您將使用這些資料來「種子」您的資料庫（用初始資料填充它）。

TypeScript

您可能也注意到大多數檔案都有 .ts 或 .tsx 副檔名。這是因為本專案使用 TypeScript 編寫。我們希望建立一個反映現代網頁開發現狀的課程。

即使您不熟悉 TypeScript 也沒關係——我們會在需要時提供 TypeScript 程式碼片段。

現在，請查看 /app/lib/definitions.ts 檔案。在這裡，我們手動定義了從資料庫返回的型別。例如，發票表格具有以下型別：

export type Invoice = {
  id: string;
  customer_id: string;
  amount: number;
  date: string;
  // 在 TypeScript 中，這稱為字串聯合型別。
  // 表示 "status" 屬性只能是 'pending' 或 'paid' 其中之一。
  status: 'pending' | 'paid';
};

透過使用 TypeScript，您可以確保不會意外將錯誤的資料格式傳遞給元件或資料庫，例如將 string 而非 number 傳遞給發票的 amount。

給 TypeScript 開發者的建議：

• 我們手動宣告了資料型別，但為了更好的型別安全性，我們推薦使用 Prisma 或 Drizzle，它們能根據資料庫結構自動生成型別。
• Next.js 會檢測您的專案是否使用 TypeScript，並自動安裝必要的套件和設定。Next.js 還附帶了TypeScript 外掛用於您的程式碼編輯器，以協助自動完成和型別安全檢查。

執行開發伺服器

執行 pnpm i 安裝專案所需的套件：

pnpm i

接著執行 pnpm dev 啟動開發伺服器：

pnpm dev

pnpm dev 會在連接埠 3000 上啟動您的 Next.js 開發伺服器。讓我們檢查它是否正常運作。

在瀏覽器中開啟 http://localhost:3000。您的首頁應如下所示，這是我們刻意未添加樣式的結果：