跳到主要內容

如何在 pnpm workspaces monorepo 中使用 Prisma ORM

10 分鐘

Prisma 是一個功能強大的 ORM，用於管理您的資料庫，當與 pnpm Workspaces 結合使用時，您可以維護精簡且模組化的 monorepo 架構。在本指南中，我們將逐步介紹如何在 pnpm Workspaces monorepo 中，於其自身的套件內設定 Prisma，從而在您的應用程式之間實現可維護的類型共享和高效的資料庫管理。

您將學到什麼：​

  • 如何使用 pnpm Workspaces 初始化 monorepo。
  • 將 Prisma 作為獨立套件整合的步驟。
  • 如何在套件之間生成和共享 Prisma Client。
  • 將 Prisma 套件整合到工作區中的應用程式。

1. 準備您的專案並配置 pnpm workspaces​

在整合 Prisma 之前，您需要設定您的專案結構。首先，為您的專案建立一個新的目錄（例如，my-monorepo）並初始化一個 Node.js 專案

mkdir my-monorepo
cd my-monorepo
pnpm init

接下來，建立一個 pnpm-workspace.yaml 檔案來定義您的工作區結構並釘住 Prisma 版本

touch pnpm-workspace.yaml

將以下配置新增到 pnpm-workspace.yaml

pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"
catalogs:
  prisma:
    prisma: latest
注意

catalogs 幫助您在整個儲存庫中釘住特定版本的 prisma。您可以在這裡了解更多關於它們的資訊。明確地在 pnpm-workspace.yaml 檔案中釘住 prisma 的最新版本。在撰寫本文時，這是版本 6.3.1。

最後，為您的應用程式和共享套件建立目錄

mkdir apps
mkdir -p packages/database

2. 設定共享資料庫套件​

本節涵蓋建立使用 Prisma 的獨立資料庫套件。該套件將包含所有資料庫模型和生成的 Prisma Client，使其可在您的 monorepo 中重複使用。

2.1. 初始化套件並安裝依賴項​

導航到 packages/database 目錄並初始化一個新套件

cd packages/database
pnpm init

使用釘住的 catalog 在您的 package.json 中將 Prisma 新增為開發依賴項

database/package.json
"devDependencies": {
  "prisma": "catalog:prisma"
}

然後安裝 Prisma

pnpm install

然後，新增其他依賴項

pnpm add typescript tsx @types/node -D

然後安裝使用 Prisma Postgres 所需的 Prisma Client 擴展

pnpm add @prisma/extension-accelerate
資訊

本指南使用 Prisma Postgres。如果您計劃使用不同的資料庫，則可以省略 @prisma/extension-accelerate 套件。

為您的 database 套件初始化一個 tsconfig.json 檔案

pnpm tsc --init

2.2. 在您的資料庫套件中設定 Prisma ORM​

透過執行以下命令，在 database 套件中使用 Prisma Postgres 的實例初始化 Prisma ORM

pnpm prisma init --db

輸入專案名稱並選擇資料庫區域。

資訊

在本指南中，我們將使用 Prisma Postgres。如果您未使用 Prisma Postgres 資料庫，則無需新增 --db 標記。

此命令

  • 將您的 CLI 連接到您的帳戶。如果您未登入或沒有帳戶，您的瀏覽器將會開啟，引導您建立新帳戶或登入現有帳戶。
  • 建立一個 prisma 目錄，其中包含用於您的資料庫模型的 schema.prisma 檔案。
  • 建立一個 .env 檔案，其中包含您的 DATABASE_URL（例如，對於 Prisma Postgres，它應該類似於 DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=eyJhbGciOiJIUzI..."）。

編輯 schema.prisma 檔案以在您的資料庫中定義 User 模型，並指定一個自訂 output 目錄以生成 Prisma Client。這確保生成的類型能正確解析

prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
  output = "../generated/client"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
}

接下來，將輔助腳本新增到您的 package.json 以簡化 Prisma 命令

database/package.json
{
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "db:generate": "prisma generate --no-engine",
    "db:migrate": "prisma migrate dev",
    "db:deploy": "prisma migrate deploy",
    "db:studio": "prisma studio"
  }
}

使用 Prisma Migrate 遷移您的資料庫變更

pnpm run db:migrate

當 CLI 提示時，輸入遷移的描述性名稱。

遷移成功後，建立一個 client.ts 檔案以使用 Accelerate 擴展初始化 Prisma Client

database/client.ts
import { PrismaClient } from "./generated/client";
import { withAccelerate } from '@prisma/extension-accelerate'

const prisma = new PrismaClient().$extends(withAccelerate())

const globalForPrisma = global as unknown as { prisma: typeof prisma }

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma

export { prisma };

然後，建立一個 index.ts 檔案以重新匯出 Prisma Client 的實例和所有生成的類型

database/index.ts
export { prisma } from "./client";
export * from "./generated/client";

至此，您的共享資料庫套件已完全配置，並準備好在您的 monorepo 中使用。

3. 設定和整合您的前端應用程式​

現在資料庫套件已設定完成，建立一個前端應用程式（使用 Next.js），該應用程式使用共享的 Prisma Client 與您的資料庫互動。

3.1. 啟動 Next.js 應用程式​

導航到 apps 目錄

cd ../../apps

建立一個名為 web 的新 Next.js 應用程式

pnpm create next-app@latest web --yes

然後，導航到 web 目錄

cd web/

從資料庫套件複製 .env 檔案，以確保相同的環境變數可用

cp ../../packages/database/.env .
重要

--yes 標記使用預設配置來啟動 Next.js 應用程式（在本指南中，它使用 app router，沒有 src/ 目錄，並使用 pnpm 作為安裝程式）。

此外，該標記可能會在 web 資料夾中自動初始化 Git 儲存庫。如果發生這種情況，請執行 rm -r .git 來移除 .git 目錄。

開啟您的 Next.js 應用程式的 package.json 檔案，並將共享的 database 套件新增為依賴項

web/package.json
"dependencies": {
  "database": "workspace:*",
  // additional dependencies
  // ...
}

執行以下命令以安裝 database 套件

pnpm install

3.2. 在您的應用程式程式碼中整合共享的 database 套件​

修改您的 Next.js 應用程式程式碼，以使用來自資料庫套件的 Prisma Client。如下更新 app/page.tsx

app/page.tsx
import { prisma } from "database";

export default async function Home() {
  const user = await prisma.user.findFirst({
    select: {
      name: true
    }
  })

  return (
    <div>
      {user?.name && <p>Hello from {user.name}</p>}
      {!user?.name && <p>No user has been added to the database yet. </p>}
    </div>
  );
}

此程式碼示範了匯入和使用共享的 Prisma Client 來查詢您的 User 模型。

3.3. 新增輔助腳本並執行您的應用程式​

將以下腳本新增到您的 monorepo 的根 package.json 中。它們確保資料庫遷移、類型生成和應用程式建置以正確的順序執行

"scripts": {
  "build": "pnpm --filter database db:deploy && pnpm --filter database db:generate  && pnpm --filter web build",
  "start": "pnpm --filter web start",
  "dev": "pnpm --filter database db:generate && pnpm --filter web dev",
  "studio": "pnpm --filter database db:studio"
}

3.4. 執行您的應用程式​

然後回到 monorepo 的根目錄

cd ../../

透過執行以下命令啟動您的開發伺服器

pnpm run dev

在瀏覽器中開啟 https://127.0.0.1:3000 以查看您的應用程式運作。

3.5. （可選）使用 Prisma Studio 將資料新增到您的資料庫​

您的資料庫中目前應該沒有資料。您可以在 CLI 中執行 pnpm run studio 以在 https://127.0.0.1:5555 啟動 Prisma Studio，以與您的資料庫互動並向其中新增資料。

下一步​

您現在已建立一個有效使用 Prisma ORM 的 monorepo，其中共享的資料庫套件已整合到 Next.js 應用程式中。

為了進一步探索和增強您的設定，請考慮閱讀如何將 Prisma ORM 與 Turborepo 搭配使用指南。