跳到主内容

如何在 Turborepo 中使用 Prisma ORM

15 分钟

Prisma 是一个强大的用于管理数据库的 ORM,而 Turborepo 简化了 monorepo 工作流程。通过结合这些工具,你可以为你的项目创建可伸缩、模块化的架构。

本指南将向你展示如何在 Turborepo monorepo 中将 Prisma 设置为一个独立的包,以便在多个应用中实现高效的配置、类型共享和数据库管理。

你将学到什么:

  • 如何在 Turborepo monorepo 中设置 Prisma。
  • 跨包生成和重用 PrismaClient 的步骤。
  • 将 Prisma 包集成到 monorepo 中的其他应用中。

1. 使用 Turborepo 创建你的 monorepo

要设置一个名为 turborepo-prisma 的 Turborepo monorepo,请运行以下命令

npx create-turbo@latest turborepo-prisma

设置完成后,选择一个项目包管理器。导航到项目根目录并安装 Turborepo 作为开发依赖

cd ./turborepo-prisma
npm install turbo --save-dev

有关安装 Turborepo 的更多信息,请参阅Turborepo 官方指南

2. 向 turborepo-prisma monorepo 添加一个新的 database

packages 目录下创建一个 database 包。然后,运行以下命令为该包创建一个 package.json 文件

cd packages/
mkdir database
cd database
touch package.json

按如下方式定义 package.json 文件

packages/database/package.json
{
"name": "@repo/db",
"version": "0.0.0"
}

接下来,安装使用 Prisma ORM 所需的依赖。使用你偏好的包管理器

npm install prisma --save-dev

3. 运行 prisma init 初始化 Prisma

database 目录下,运行以下命令初始化 prisma

npx prisma init --db --output ../generated/prisma

这将在 packages/database 目录下创建几个文件

  • prisma/schema.prisma 是你的 Prisma schema 所在的位置。在这里,你可以修改数据库的形状。prisma init 命令默认会创建一个使用 PostgreSQL 的配置。你可以修改 schema 以使用 Prisma ORM 支持的任何其他数据库
  • .gitignore 添加了一些要忽略的 git 文件
  • .env 允许你手动指定 Prisma 的 DATABASE_URL

packages/database/prisma/schema.prisma 中为你的 Prisma schema 添加一个 model

packages/database/prisma/schema.prisma
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}

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

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

建议将 ../generated/prisma 添加到 .gitignore 文件中,因为它包含特定于平台的二进制文件,这可能导致跨不同环境的兼容性问题。

自定义目录中生成 Prisma 类型的重要性

schema.prisma 文件中,我们指定了一个自定义的 output 路径,Prisma 将在那里生成其类型。这确保了 Prisma 的类型在不同的包管理器之间正确解析。

在本指南中,类型将在 database/generated/prisma 目录中生成。

4. 创建执行 Prisma CLI 命令的脚本

让我们在 packages/database 目录下的 package.json 中添加一些脚本

packages/database/package.json
{
"name": "@repo/db",
"version": "0.0.0",
"scripts": {
"db:generate": "prisma generate",
"db:migrate": "prisma migrate dev --skip-generate",
"db:deploy": "prisma migrate deploy"
},
"devDependencies": {
"prisma": "^6.6.0"
},
"dependencies": {
"@prisma/client": "^6.6.0"
}
}

我们还在根目录的 turbo.json 中添加这些脚本

turbo.json
{
"$schema": "https://turbo.net.cn/schema.json",
"ui": "tui",
"tasks": {
"build": {
"dependsOn": ["^build"],
"inputs": ["$TURBO_DEFAULT$", ".env*"],
"outputs": [".next/**", "!.next/cache/**"]
},
"lint": {
"dependsOn": ["^lint"]
},
"check-types": {
"dependsOn": ["^check-types"]
},
"dev": {
"cache": false,
"persistent": true
},
"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/prisma";

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/prisma" // exports generated types from prisma

遵循即时打包模式(Just-in-Time packaging pattern),并在 packages/database/package.json 中创建一个包的入口点

packages/database/package.json
{
"name": "@repo/db",
"version": "0.0.0",
"scripts": {
"db:generate": "npx prisma generate",
"db:migrate": "npx prisma migrate dev --skip-generate",
"db:deploy": "npx prisma migrate deploy"
},
"devDependencies": {
"prisma": "^6.6.0"
},
"dependencies": {
"@prisma/client": "^6.6.0"
}
"exports": {
".": "./src/index.ts"
},
}

通过完成这些步骤,你将使 Prisma 类型和 PrismaClient 实例在整个 monorepo 中都可以访问。

6. 将 database 包导入 monorepo 中的 web 应用

turborepo-prisma 项目在 apps/web 应该有一个名为 web 的应用。将 database 依赖添加到 apps/web/package.json

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

apps/web 目录下运行你包管理器的安装命令

cd apps/web
npm install

让我们在 web 应用中从 database 包导入实例化的 prisma 客户端。

apps/web/app 目录下,打开 page.tsx 文件并添加以下代码

apps/web/app/page.tsx
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` 文件内容复制到其中

apps/web/.env
DATABASE_URL="Same database url as used in the database directory"
注意

如果你想在 Turborepo 设置中,在根目录下跨应用和包使用一个 `.env` 文件,请考虑使用像 dotenvx 这样的包。

要实现这一点,请更新每个包或应用的 package.json 文件,以确保它们从共享的 `.env` 文件加载所需的环境变量。有关详细说明,请参阅针对 Turborepo 的 dotenvx 指南

请记住,Turborepo 建议为每个包使用单独的 `.env` 文件,以提高模块化并避免潜在的冲突。

7. 设置依赖任务

db:generatedb:deploy 脚本尚未针对 monorepo 设置进行优化,但它们对于 devbuild 任务至关重要。

如果新开发者在没有先运行 db:generate 的情况下在应用上运行 turbo dev,他们将会遇到错误。

为了防止这种情况发生,请确保在运行 devbuild 之前始终执行 db:generate。此外,还要确保在 db:build 之前执行 db:deploydb:generate。以下是如何在 turbo.json 文件中进行配置:

turbo.json
{
"$schema": "https://turbo.net.cn/schema.json",
"ui": "tui",
"tasks": {
"build": {
"dependsOn": ["^build", "^db:generate"],
"inputs": ["$TURBO_DEFAULT$", ".env*"],
"outputs": [".next/**", "!.next/cache/**"]
},
"lint": {
"dependsOn": ["^lint"]
},
"check-types": {
"dependsOn": ["^check-types"]
},
"dev": {
"dependsOn": ["^db:generate"],
"cache": false,
"persistent": true
},
"db:generate": {
"cache": false
},
"db:migrate": {
"cache": false,
"persistent": true
},
"db:deploy": {
"cache": false
}
}
}

8. 在开发模式下运行项目

警告

在启动开发服务器之前,请注意,如果你正在使用 Next.js v15.2.0,请不要使用 Turbopack,因为存在一个已知问题。通过更新 apps/web/package.json 从你的 dev 脚本中删除 Turbopack

apps/web/package.json
"script":{
"dev": "next dev --turbopack --port 3000",
"dev": "next dev --port 3000",
}

然后从项目根目录运行项目

npx turbo run dev --filter=web

导航到 http://localhost:3000,你应该会看到消息

No user added yet
注意

你可以通过创建 seed 脚本或手动使用Prisma Studio 向数据库添加用户。

要使用 Prisma Studio 通过 GUI 手动添加数据,请导航到 packages/database 目录内,并使用你的包管理器运行 prisma studio

npx prisma studio

此命令会在 http://localhost:5555 启动一个带有 GUI 的服务器,允许你查看和修改数据。

恭喜,你已经完成了 Prisma 在 Turborepo 中的设置!

下一步

  • 扩展你的 Prisma models 以处理更复杂的数据关系。
  • 实现额外的 CRUD 操作以增强你的应用功能。
  • 查看Prisma Postgres,了解如何扩展你的应用。

更多信息


与 Prisma 保持联系

与以下方式联系,继续你的 Prisma 之旅 我们活跃的社区。保持了解,参与其中,并与其他开发者协作

我们真心珍视你的参与,并期待你成为我们社区的一员!