> ## 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로 웹 + 모바일 SaaS 구축하기 (모노레포 실전 가이드)

크로스 플랫폼 SaaS 아키텍처 실전 가이드: pnpm 모노레포에서 Next.js 16과 React Native Expo를 유기적으로 결합하고 Better Auth와 Drizzle ORM을 공유하는 방법.

_게시일 2026-11-06._
_2026-11-06 업데이트됨._

> **Next.js와 Expo가 하나의 모노레포에서 코드를 공유하는 방법은?**
> 모듈 경계 설정과 번들러 구성에 따라 다릅니다. 가장 이상적인 아키텍처는 pnpm과 Turborepo를 사용하여 공유 DB 모델, 유효성 검사, API 계약을 헤드리스 내부 패키지로 격리하는 것입니다. Next.js 16 서버는 Drizzle ORM을 직접 실행하고, Expo 모바일 앱은 타입 안정성이 보장된 HTTP 엔드포인트를 통해 통신하며 expo-secure-store로 인증 토큰을 안전하게 유지합니다. supastack은 Metro와 Turbopack 간의 번들러 충돌 없이 이 구조를 완벽히 사전 구성해 제공합니다.

## 크로스 플랫폼 SaaS의 가장 큰 난제: 번들러 불일치

모든 창업자는 모바일 앱이 푸시 알림과 홈 화면 위젯을 통해 사용자 유지율과 일간 활성 사용자를 극적으로 끌어올린다는 사실을 잘 알고 있습니다. 하지만 Next.js와 React Native Expo를 단일 모노레포에 통합하는 일은 악명 높을 정도로 까다롭습니다.

Next.js는 Node.js와 Edge 런타임 기반의 Turbopack/Webpack을 사용하고, Expo는 React Native 모바일 JS 엔진을 사용하는 Metro 번들러를 사용합니다. 어설픈 코드 공유는 Metro가 Node의 `crypto` 모듈을 파싱하려다 충돌하거나 Turbopack이 모바일 JSX 문법에서 멈추는 비극으로 끝납니다. 해답은 명확한 헤드리스 패키지 캡슐화에 있습니다.


## 헤드리스 공유 패키지 설계: 인증, 스키마 및 계약

실전 모노레포에서 애플리케이션(`apps/web`과 `apps/mobile`)은 얇은 UI 프레젠테이션 계층이어야 합니다. 핵심 비즈니스 로직과 DB 정의는 `packages/` 내부 패키지에 위치해야 합니다:

`@supastack/db`: Drizzle ORM 테이블 정의와 마이그레이션을 담당합니다. 서버 런타임만 DB 인스턴스를 직접 연결하고 클라이언트는 추론된 타입만 참조합니다.

`@supastack/auth`: Better Auth를 구성하며 두 개의 진입점을 제공합니다: 서버 라우트 핸들러용 엔드포인트와 웹/모바일 양쪽에서 호출하는 헤드리스 클라이언트 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 })] : [],
  });
}
```


## 통합 인증 처리: 웹의 쿠키와 모바일의 SecureStore

웹과 모바일은 서로 다른 세션 저장 메커니즘을 필요로 합니다. 웹 브라우저에서 Next.js는 HTTP-only, `SameSite=Lax` 쿠키를 설정하여 CSRF 보호와 서버 컴포넌트 하이드레이션을 매끄럽게 처리합니다.

반면 모바일 환경에서는 쿠키가 불안정하므로 OAuth 완료 시 보안 Bearer 토큰을 발급받아 `expo-secure-store`를 통해 iOS 키체인이나 Android 키스토어에 안전하게 보관합니다. 모바일 요청은 `Authorization: Bearer <token>` 헤더를 포함하며 공통 Better Auth 미들웨어에서 원활하게 검증됩니다.


## CI/CD 및 배포 파이프라인: Vercel, EAS Build, 버전 동기화

하나의 리포지토리에서 웹과 모바일을 관리하면 동기화된 릴리스의 혜택을 온전히 누릴 수 있습니다. `@supastack/db`의 마이그레이션이 머지되면 Next.js 백엔드가 Vercel이나 Cloud Run에 즉시 배포됩니다.

동시에 Expo Application Services(EAS Build)가 Apple TestFlight와 Google Play 내부 테스트를 위한 네이티브 바이너리를 자동 빌드합니다. 공유 패키지의 버전을 고정함으로써 두 개의 독립 리포지토리를 운영할 때 생기는 치명적인 버전 불일치 버그를 완벽히 해결합니다.