跳至主要內容

如何在 Turborepo 中使用 Prisma ORM

Prisma 是一個強大的 ORM，用於管理資料庫，而 Turborepo 簡化了 monorepo 工作流程。透過結合這些工具，您可以為您的專案創建一個可擴展、模組化的架構。

本指南將向您展示如何在 Turborepo monorepo 中將 Prisma 設定為獨立套件，從而在多個應用程式中實現高效的配置、類型共享和資料庫管理。

您將學到：​

  • 如何在 Turborepo monorepo 中設定 Prisma。
  • 在多個套件中生成和重複使用 PrismaClient 的步驟。
  • 將 Prisma 套件整合到 monorepo 中的其他應用程式。
注意

本指南使用 Turborepo 版本 2.3.3 和 Prisma ORM 版本 6.1.0 進行測試。

1. 使用 turborepo 建立您的 monorepo​

若要設定名為 hello-world 的 Turborepo monorepo，請執行以下命令

npx create-turbo@latest hello-world

設定完成後，為專案選擇一個套件管理器。導覽至專案根目錄並將 Turborepo 安裝為開發依賴項

cd ./hello-world
npm install turbo --save-dev

有關安裝 Turborepo 的更多資訊，請參閱官方 Turborepo 指南。

2. 將新的 database 套件新增至 hello-world monorepo​

在 packages 目錄中建立 database 套件。然後，執行以下命令為套件建立 package.json 檔案

cd packages/
mkdir database
cd database
touch package.json

定義 package.json 檔案如下

{
  "name": "@repo/db",
  "version": "0.0.0"
}

接下來，安裝使用 Prisma ORM 所需的依賴項。使用您偏好的套件管理器

npm install prisma --save-dev
npm install @prisma/client

3. 執行 prisma init 初始化 prisma​

在 database 目錄內，執行以下命令初始化 prisma

npx prisma init

這應該會在 packages/database 內建立數個檔案

  • schema.prisma 是您的 Prisma schema 所在的位置。在這裡，您可以修改資料庫的形狀。預設情況下，prisma init 命令將建立用於 PostgreSQL 的配置。您可以修改 schema 以使用 Prisma ORM 支援的任何其他資料庫。
  • .gitignore 將一些忽略的檔案新增至 git
  • .env 可讓您手動指定 prisma 的 DATABASE_URL。
警告

請確保將 packages/database/.env 內的 DATABASE_URL 替換為有效的資料庫 URL。

在 database/prisma/schema.prisma 中將模型新增至您的 Prisma schema

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

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

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

在自訂目錄中產生 Prisma 類型的重要性​

在 schema.prisma 檔案中，我們指定一個自訂 output 路徑，Prisma 將在此路徑產生其類型。這可確保 Prisma 的類型在不同的套件管理器之間正確解析。

在本指南中，類型將在 database/generated/client 目錄中產生。

4. 建立指令碼以執行 Prisma CLI 命令​

讓我們將一些指令碼新增至 packages/database 內的 package.json

{
  "scripts": {
    "db:generate": "prisma generate",
    "db:migrate": "prisma migrate dev --skip-generate",
    "db:deploy": "prisma migrate deploy"
  }
}

讓我們也將這些指令碼新增至根目錄中的 turbo.json

{
  "tasks": {
    "db:generate": {
      "cache": false
    },
    "db:migrate": {
      "cache": false,
      "persistent": true // This is necessary to interact with the CLI and assign names to your database migrations.
    },
    "db:deploy": {
      "cache": false
    }
  }
}

1. 遷移您的 prisma.schema 並產生類型​

導覽至專案根目錄並執行以下命令，自動遷移我們的資料庫

npx turbo db:migrate

2. 產生您的 prisma.schema​

若要從 Prisma schema 產生類型，請從專案根目錄執行

npx turbo db:generate

5. 匯出 prisma 類型和 PrismaClient 的執行個體，以便在 monorepo 中使用​

接下來，匯出產生的類型和 PrismaClient 的執行個體，以便在您的應用程式中使用。

在 packages/database 目錄中，建立 src 資料夾並新增 client.ts 檔案。此檔案將定義 PrismaClient 的執行個體

packages/database/src/client.ts
import { PrismaClient } from "../generated/client";

const globalForPrisma = global as unknown as { prisma: PrismaClient };

export const prisma =
  globalForPrisma.prisma || new PrismaClient();

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

然後在 src 資料夾中建立 index.ts 檔案，以重新匯出產生的 prisma 類型和 PrismaClient 執行個體

packages/database/src/index.ts
export { prisma } from './client' // exports instance of prisma 
export * from "../generated/client" // exports generated types from prisma

遵循即時封裝模式 並在 packages/database/package.json 內建立套件的進入點

{
  "exports": {
    ".": "./src/index.ts"
  } 
}

完成這些步驟後，您將使 Prisma 類型和 PrismaClient 執行個體在整個 monorepo 中可存取。

6. 將 database 套件匯入 monorepo 中的 web 應用程式​

hello-world 專案應該在 apps/web 有一個名為 web 的應用程式。將 database 依賴項新增至 apps/web/package.json

{
  "dependencies": {
    "@repo/db": "*"
  }
}

在 apps/web 目錄內執行您的套件管理器的安裝命令

cd apps/web
npm install

讓我們將來自 database 套件的實例化 prisma client 匯入 page.tsx 檔案中的 web 應用程式

import styles from "./page.module.css";
import { prisma } from "@repo/db";

export default async function Home() {
  const user = await prisma.user.findFirst() 
  return (
    <div className={styles.page}>
      {user?.name ?? "No user added yet"}
    </div>
  );
}

然後在 web 目錄中建立 .env 檔案，並複製 database 目錄中包含 DATABASE_URL 的 .env 檔案的內容。

DATABASE_URL="Same database url as used in the database directory"
注意

如果您想在 Turborepo 設定中，在應用程式和套件中使用根目錄中的單一 .env 檔案，請考慮使用像 dotenvx 的套件。

若要實作此功能，請更新每個套件或應用程式的 package.json 檔案，以確保它們從共用的 .env 檔案載入所需的環境變數。如需詳細指示，請參閱適用於 Turborepo 的 dotenvx 指南。

請記住，Turborepo 建議為每個套件使用單獨的 .env 檔案，以促進模組化並避免潛在的衝突。

7. 設定相依任務​

db:generate 和 db:deploy 腳本尚未針對 monorepo 設定進行最佳化，但對於 dev 和 build 任務至關重要。

如果新的開發人員在沒有先執行 db:generate 的情況下在應用程式上執行 turbo dev，他們將會遇到錯誤。

為了防止這種情況，請確保 db:generate 始終在執行 dev 或 build 之前執行。此外，請確保 db:deploy 和 db:generate 都在 db:build 之前執行。以下是如何在您的 turbo.json 檔案中設定此項。

{
  "tasks": {
    "dev": {
      "dependsOn": ["^db:generate"],
      "cache": false
      // Additional configuration for dev tasks
    },
    "build": {
      "dependsOn": ["^db:generate"],
      // Additional configuration for build tasks
    }
  }
}

8. 在開發中執行專案​

然後從專案根目錄執行專案

npx turbo run dev --filter=web

導覽至 https://127.0.0.1:3000，您應該會看到訊息

No user added yet
注意

您可以透過建立種子腳本或手動使用 Prisma Studio，將使用者新增至資料庫。

若要使用 Prisma Studio 透過 GUI 手動新增資料，請導覽至 packages/database 目錄內，並使用您的套件管理器執行 prisma studio。

npx prisma studio

此命令會啟動一個伺服器，其 GUI 位於 https://127.0.0.1:5555，讓您可以檢視和修改您的資料。

恭喜，您已完成 Turborepo 的 Prisma 設定！