> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 如何用 Next.js 與 Expo 建構 Web + 行動端 SaaS (Monorepo 實戰指南)

跨端 SaaS 架構實戰：在 pnpm monorepo 中統一編排 Next.js 16 與 React Native Expo，共享 Better Auth 與 Drizzle ORM 資料層。

_釋出於 2026-11-06._
_更新於 2026-11-06._

> **如何在一套 monorepo 中讓 Next.js 和 Expo 共享程式碼？**
> 這取決於你的模組邊界與打包工具配置。最穩健的架構是使用 pnpm 與 Turborepo 將共享的資料模型、驗證模式與 API 契約隔離在無頭內部套件中。Next.js 16 伺服端透過 Node/Edge 執行階段直接執行 Drizzle ORM，而 Expo 行動端透過型別化 HTTP 介面通訊，並利用 expo-secure-store 原生持久化認證憑證。supastack 開箱提供了這套完整工程配置，徹底解決了 Metro 與 Turbopack 之間的打包衝突。

## 跨端 SaaS 最難啃的骨頭：打包工具的裂痕

每位 SaaS 創辦人都知道，借助系統級推播通知與手機主畫面入口，行動 App 能大幅提升使用者黏著度、回購率與每日活躍數據。然而，將 Next.js 與 React Native Expo 塞進同一個 monorepo 通常是一場惡夢。

Next.js 基於 Turbopack 或 Webpack，依賴 Node.js 與 Edge 執行階段；而 Expo 依賴 Metro 打包器與 React Native 的行動端 JS 引擎。最直覺的程式碼複用嘗試往往以災難告終：Metro 試圖解析 Node 的 `crypto` 或 `stream` 原生模組報錯，而 Turbopack 則被 React Native 特有的 JSX 語法阻塞。優雅解法的核心是嚴格的無頭套件封裝。


## 設計無頭共享套件：認證、Schema 與型別契約

在生產級工程中，應用端（`apps/web` 與 `apps/mobile`）應該僅僅是薄薄的 UI 表現層。業務核心、資料庫模型與認證配置應當歸攏在 `packages/` 目錄下的內部套件中：

`@supastack/db`：存放 Drizzle ORM 表結構定義、多表關聯與遷移檔案。僅伺服端能引用資料庫連線實例，客戶端只引入推導出的 TypeScript 型別。

`@supastack/auth`：配置 Better Auth，並提供雙入口點：供伺服端路由使用的管理端點，以及供 Web 和行動端共同呼叫的無頭 Client SDK。

`@supastack/config`：在編譯階段利用 Zod 對環境變數進行強型別校驗，杜絕執行階段的配置缺失當機。

```
// packages/auth/src/client.ts
import { createAuthClient } from "better-auth/react";
import { expoClient } from "@better-auth/expo/client";

export function createCrossPlatformAuthClient(baseURL: string, storage?: any) {
  return createAuthClient({
    baseURL,
    plugins: storage ? [expoClient({ scheme: "myapp", storage })] : [],
  });
}
```


## 統一跨端認證：Web 端 Cookie 與行動端 SecureStore

Web 端與行動端需要完全不同的工作階段持久化機制。在 Web 瀏覽器中，Next.js 下發 HTTP-only、`SameSite=Lax` 的安全 Cookie，自動獲得 CSRF 防護與伺服端元件無縫注水。

在原生手機端，Cookie 在各系統的 WebView 中極不可靠。Expo 應用透過 OAuth 或 Magic Link 交換獲取安全的 Bearer 工作階段 Token，並借助 `expo-secure-store` 安全持久化到 iOS Keychain 或 Android Keystore 中。行動端出站請求攜帶 `Authorization: Bearer <token>` 請求標頭，由共享的 Better Auth 統一中介軟體校驗。


## CI/CD 與多端發布流水線：Vercel、EAS Build 與版本同步

在同一個程式碼存放庫中維護 Web 與行動端，能帶來版本協同更新的巨大紅利。當 `@supastack/db` 中的資料庫遷移合併後，Next.js 後端可在 Vercel 或 Cloud Run 上數秒內完成熱部署。

與此同時，Expo Application Services（EAS Build）自動觸發針對 Apple TestFlight 與 Google Play 內部測試軌道的原生打包。透過在 monorepo 內鎖定共享依賴版本，你將徹底告別雙存放庫間版本脫節引發的幽靈故障。