如何在 Next.js 應用程式中嵌入 Prisma Studio

15 分鐘

您可以直接使用 @prisma/studio-core 套件將 Prisma Studio 直接嵌入到您的 Next.js 應用程式中。本指南將帶您完成設定，以便您直接在應用程式內部管理資料庫，無需另外執行 Prisma Studio。

完成本指南後，您將擁有一個內建 Prisma Studio 的 Next.js 應用程式，讓您能直接從應用程式介面瀏覽和編輯資料庫。

在以下場景中，嵌入 Prisma Studio 非常實用：

• 建立用於編輯資料的簡易管理後台
• 支援多租戶 (multi-tenant) 應用程式，其中每個使用者都有自己的資料庫
• 提供使用者一個檢視及編輯其資料的簡單方式

注意

可嵌入式 Prisma Studio 為免費並採用 Apache 2.0 授權。

✔️ 可免費在正式環境中使用 ⚠️ 必須保持 Prisma 品牌標誌可見且不得變更 🔐 若要移除品牌標誌或了解即將推出的合作夥伴專屬功能，請聯繫 partnerships@prisma.io

目前，嵌入式 Prisma Studio 支援 Prisma Postgres，未來將支援更多資料庫。

先決條件

• Node.js 20+
• 具備 React 和 Next.js 的基礎知識
• 一個 Prisma Postgres 資料庫

1. 設定 Next.js

首先，在您想要建置應用程式的目錄中建立一個新的 Next.js 專案

npx create-next-app@latest nextjs-studio-embed

系統會提示您回答幾個關於專案的問題。請全部選擇預設值。

資訊

參考內容如下

• TypeScript
• ESLint
• Tailwind CSS
• 不使用 src 目錄
• App Router
• Turbopack
• 選擇預設的導入別名 (import alias)

接著，切換到專案目錄

cd nextjs-studio-embed

2. 設定 Prisma ORM 和 Prisma Postgres

2.1. 安裝 Prisma 依賴套件

安裝所需的 Prisma 套件

npm install prisma tsx @types/pg --save-dev
npm install @prisma/extension-accelerate @prisma/client @prisma/adapter-pg dotenv pg

資訊

如果您使用的是不同的資料庫提供者（MySQL、SQL Server、SQLite），請安裝相應的驅動程式適配器套件，而不是 @prisma/adapter-pg。如需更多資訊，請參閱資料庫驅動程式。

2.2. 使用 Prisma Postgres 初始化 Prisma

在您的專案中初始化 Prisma 並建立 Prisma Postgres 資料庫

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

資訊

在設定 Prisma Postgres 資料庫時，您需要回答幾個問題。請選擇離您最近的地區，並為您的資料庫取一個易於辨識的名稱，例如「My __________ Project」

prisma init --db 指令會建立：

• 一個包含 schema.prisma 檔案的 prisma/ 目錄
• 一個用於設定 Prisma 的 prisma.config.ts 檔案
• 一個新的 Prisma Postgres 資料庫
• 一個包含 DATABASE_URL 的 .env 檔案
• 一個用於存放 Prisma Client 的 app/generated/prisma 輸出目錄

2.3. 定義您的資料庫結構 (Schema)

開啟 prisma/schema.prisma 並將內容取代為

prisma/schema.prisma

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

datasource db {
  provider = "postgresql"
}


model User {
  id    Int    @id @default(autoincrement())
  name  String
  email String @unique
  posts Post[]
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  authorId  Int
  author    User     @relation(fields: [authorId], references: [id])
  createdAt DateTime @default(now())
}

2.4 在 prisma.config.ts 中加入 dotenv

要存取 .env 檔案中的變數，可以透過執行階段載入，或是使用 dotenv。在 prisma.config.ts 的頂部包含一個 dotenv 的匯入：

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config';
export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
});

2.5. 將結構應用於您的資料庫

產生 Prisma Client 並應用結構

npx prisma migrate dev --name init
npx prisma generate

此動作會在您的 Prisma Postgres 資料庫中建立資料表，並產生 Prisma Client。

2.6. 為資料庫填充種子資料 (選擇性)

建立一個種子檔案來新增一些範例資料。在 prisma 資料夾中建立一個 seed.ts 檔案，並加入以下程式碼

prisma/seed.ts

import { PrismaClient } from '../app/generated/prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'

const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL!,
})

const prisma = new PrismaClient({
  adapter,
})

async function main() {
  // Create users
  const user1 = await prisma.user.create({
    data: {
      name: 'Alice Johnson',
      email: 'alice@example.com',
    },
  })

  const user2 = await prisma.user.create({
    data: {
      name: 'Bob Smith',
      email: 'bob@example.com',
    },
  })

  // Create posts
  await prisma.post.create({
    data: {
      title: 'Getting Started with Next.js',
      content: 'Next.js is a powerful React framework...',
      published: true,
      authorId: user1.id,
    },
  })

  await prisma.post.create({
    data: {
      title: 'Database Management with Prisma',
      content: 'Prisma makes database management easy...',
      published: false,
      authorId: user2.id,
    },
  })

  console.log('Database seeded successfully!')
}

main()
  .catch((e) => {
    console.error(e)
    process.exit(1)
  })
  .finally(async () => {
    await prisma.$disconnect()
  })

在 prisma.config.ts 中加入種子指令碼 (seed script)

prisma.config.ts

import 'dotenv/config';
import { defineConfig, env } from 'prisma/config';
export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
    seed: `tsx prisma/seed.ts`,
  },
  datasource: {
    url: env('DIRECT_URL'),
  },
});

執行種子指令碼

npx prisma db seed

3. 在您的應用程式中設定嵌入式 Prisma Studio

現在您已設定好 Prisma ORM 和 Prisma Postgres，可以將 Prisma Studio 嵌入到您的 Next.js 應用程式中。

3.1. 安裝 Prisma Studio Core 套件

安裝提供嵌入式組件的 @prisma/studio-core 套件

npm install @prisma/studio-core

注意

如果在安裝 @prisma/studio-core 時遇到依賴項解析錯誤，您可以透過以下指令強制安裝：

npm install @prisma/studio-core --force

如果您使用 yarn、pnpm 或其他套件管理工具，請使用該工具對應的旗標。

@prisma/studio-core 提供了 Studio React 組件，用於在您的應用程式中渲染 Prisma Studio。Studio 組件接受一個 executor，該執行器可存取您後端的一個自定義端點。後端會使用您的 API 金鑰來識別正確的 Prisma Postgres 執行個體，並將 SQL 查詢傳送給它。

3.2. 建立 Studio 包裝組件

建立一個 components 資料夾並加入一個名為 StudioWrapper.tsx 的新檔案。此檔案將包裝 Studio 組件並提供一致的版面配置

components/StudioWrapper.tsx

'use client';
import "@prisma/studio-core/ui/index.css";
import { ReactNode } from 'react';

interface StudioWrapperProps {
  children: ReactNode;
}

export default function StudioWrapper({ children }: StudioWrapperProps) {
  return (
    <div className="min-h-screen bg-gray-50">
      <header className="bg-white shadow-sm border-b">
        <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
          <div className="flex justify-between items-center py-4">
            <h1 className="text-2xl font-bold text-gray-900">
              Database Studio
            </h1>
            <div className="text-sm text-gray-500">
              Powered by Prisma Studio
            </div>
          </div>
        </div>
      </header>
      <main className="max-w-7xl mx-auto">
        <div className="h-[calc(100vh-80px)]">
          {children}
        </div>
      </main>
    </div>
  );
}

3.3. 建立 API 端點以將 SQL 查詢傳送至 Prisma Studio

接下來，設定一個可與 Prisma Studio 通訊的後端端點。此端點接收來自嵌入式 Studio UI 的 SQL 查詢，將其轉發至您的 Prisma Postgres 資料庫，然後將結果（或錯誤）傳回前端。

為此，請在 app 目錄內建立一個名為 api 的新資料夾。在裡面，加入一個 studio 資料夾以及一個 route.ts 檔案。此檔案將處理傳送至 /api/studio 的所有請求，並作為前端 Studio 組件與後端資料庫之間的橋樑

app/api/studio/route.ts

import "dotenv/config"
import { createPrismaPostgresHttpClient } from "@prisma/studio-core/data/ppg";
import { serializeError } from "@prisma/studio-core/data/bff";

const CORS_HEADERS = {
  "Access-Control-Allow-Origin": "*", // Change to your domain in production
  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type, Authorization",
};

// Use dynamic rendering for database operations
export const dynamic = "force-dynamic";

export async function GET() {
  return Response.json(
    { message: "Studio API endpoint is running" },
    { headers: CORS_HEADERS }
  );
}

export async function POST(request: Request) {
  try {
    const body = await request.json();
    const query = body.query;

    if (!query) {
      return Response.json([serializeError(new Error("Query is required"))], {
        status: 400,
        headers: CORS_HEADERS,
      });
    }

    const url = process.env.DATABASE_URL;
    if (!url) {
      const message = "❌ Environment variable DATABASE_URL is missing.";
      return Response.json([serializeError(new Error(message))], {
        status: 500,
        headers: CORS_HEADERS,
      });
    }

    const [error, results] = await createPrismaPostgresHttpClient({
      url,
    }).execute(query);

    if (error) {
      return Response.json([serializeError(error)], {
        headers: CORS_HEADERS,
      });
    }

    return Response.json([null, results], { headers: CORS_HEADERS });
  } catch (err) {
    return Response.json([serializeError(err)], {
      status: 400,
      headers: CORS_HEADERS,
    });
  }
}

// Handle preflight requests for CORS
export async function OPTIONS() {
  return new Response(null, { status: 204, headers: CORS_HEADERS });
}

3.4. 建立主要的 Studio 頁面

開啟 app/page.tsx 檔案並將現有程式碼取代為以下內容，以渲染嵌入式 Studio

app/page.tsx

'use client';

import dynamic from "next/dynamic";
import { createPostgresAdapter } from "@prisma/studio-core/data/postgres-core";
import { createStudioBFFClient } from "@prisma/studio-core/data/bff";
import { useMemo, Suspense } from "react";
import StudioWrapper from "@/components/StudioWrapper";

// Dynamically import Studio with no SSR to avoid hydration issues
const Studio = dynamic(
  () => import("@prisma/studio-core/ui").then(mod => mod.Studio),
  {
    ssr: false
  }
);

// Loading component
const StudioLoading = () => (
  <div className="flex items-center justify-center h-full">
    <div className="text-center">
      <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-600 mx-auto"></div>
      <p className="mt-4 text-gray-600">Loading Studio...</p>
    </div>
  </div>
);

// Client-only Studio component
const ClientOnlyStudio = () => {
  const adapter = useMemo(() => {
    // Create the HTTP client that communicates with our API endpoint
    const executor = createStudioBFFClient({
      url: "/api/studio",
    });

    // Create the Postgres adapter using the executor
    return createPostgresAdapter({ executor });
  }, []);

  return <Studio adapter={adapter} />;
};

export default function App() {
  return (
    <StudioWrapper>
      <Suspense fallback={<StudioLoading />}>
        <ClientOnlyStudio />
      </Suspense>
    </StudioWrapper>
  );
}

3.5. 啟動您的開發伺服器並測試嵌入式 Studio

啟動您的 Next.js 開發伺服器

npm run dev

開啟瀏覽器並前往 https://:3000。您現在應該可以看到 Prisma Studio 正在您的應用程式中執行

請檢查以下內容：

1. Prisma Studio 介面：完整的 Prisma Studio UI 應該會在您的應用程式版面中渲染出來。
2. 您的資料：您定義的 User 和 Post 資料表（以及任何填充的種子資料）應該會出現。
3. 互動式功能:
   • 在資料表中瀏覽及篩選記錄
   • 透過雙擊儲存格來直接編輯數值
   • 使用「Add record」按鈕新增記錄
   • 刪除不再需要的記錄
   • 透過在相關聯的資料表之間導覽來探索關係

透過測試基本功能來驗證一切是否運作正常

• 點擊不同的資料表以確認您的資料已載入。
• 更新一筆記錄以檢查變更是否已儲存。
• 新增一筆記錄並確認它是否立即顯示。
• 嘗試篩選資料以確保查詢執行正確。
• 導覽關聯關係（例如，檢視使用者的貼文）以確認關聯運作正常。

一旦這些操作按預期運作，您的嵌入式 Prisma Studio 即設定完畢並已連線至您的 Prisma Postgres 資料庫。

後續步驟

至此，您已讓 Prisma Studio 在 Next.js 應用程式內執行，並連接至 Prisma Postgres 資料庫。您無需離開應用程式即可瀏覽、編輯和管理資料。若要讓此設定適用於正式環境，請考慮以下改進：

1. 加入驗證機制：目前，任何能開啟您應用程式的人都可以存取 Prisma Studio。請加入使用者驗證，並僅允許特定角色（例如管理員）使用嵌入式 Studio。您可以透過在執行查詢前檢查 /api/studio 端點中的驗證權杖來實現此目的。

2. 使用環境專屬設定：在開發階段，您可能會需要測試資料庫，而在正式環境中則需要獨立的線上資料庫。請更新您的 .env 檔案，為每個環境使用不同的 DATABASE_URL 值，並確認您的 /api/studio 端點讀取的是正確的數值。

3. 套用自定義樣式：Studio 組件預設提供了外觀。您可以傳入您自己的主題並調整顏色、字體或品牌標誌，使其與您的應用程式其他部分保持一致。這有助於讓 Studio 感覺像是應用程式的一部分，而不是一個獨立的工具。

透過加入驗證機制、環境專屬設定和樣式，您可以將目前的測試原型轉變為安全且精緻的正式環境設定。

如需更多模式與範例，請參閱 Prisma Studio Core 範例儲存庫，其中包含了使用 Hono.js 和 React 的替代實作。如果您偏好引導式教學，請觀看 YouTube 影片：**Use Prisma Studio in Your Own Applications**。

與 Prisma 保持聯繫

透過以下方式與我們聯繫，繼續您的 Prisma 旅程： 我們的活躍社群。保持資訊靈通、參與其中，並與其他開發者合作

• 在 X 上關注我們 以獲取公告、現場活動和實用技巧。
• 加入我們的 Discord 提出問題、與社群對話，並透過對話獲得積極支援。
• 在 YouTube 上訂閱 查看教學、演示和直播。
• 在 GitHub 上交流 透過為存放庫加星標、報告問題或為 issue 做出貢獻。

我們衷心感謝您的參與，並期待您成為我們社群的一份子！