Next.js Multi-tenant 가이드 정리

1. 개요

Next.js로 멀티테넌트(Multi-tenant) 앱을 만들 때, Next.js 공식 문서는 “추천 아키텍처 예제”를 안내합니다.
가이드 페이지 자체는 자세한 구현을 길게 설명하기보다, **공식 예제(Starter Kit)**를 참고하라고 되어 있습니다.

이 문서에서는:

  1. 공식 문서가 안내하는 “예제의 핵심”을 요약하고
  2. 실무에서 멀티테넌트를 설계할 때 체크할 포인트를 정리합니다.

2. 공식 예제(Platforms Starter Kit) 요약

Next.js 공식 문서에서 안내하는 예제는 다음 특징을 갖습니다.

  • App Router 기반 (Next.js 15)
  • 서브도메인 기반 멀티테넌트 (tenant.yourdomain.com)
  • Next.js Middleware로 서브도메인 라우팅 처리
  • 테넌트별 콘텐츠/페이지 제공 + 공통 레이아웃/컴포넌트 공유
  • Redis(Upstash)로 테넌트 데이터 저장
  • 테넌트 관리용 Admin 인터페이스 제공
  • 로컬 개발에서도 서브도메인 테스트 지원 (http://[tenant-name].localhost:3000)
  • Vercel Preview 배포와 호환되도록 미들웨어가 환경별 서브도메인 감지를 지원

3. 멀티테넌트 구현 설계 포인트

3.1 테넌트 식별 방식 결정

  • 서브도메인 기반: tenant.example.com

    • 장점: URL이 깔끔, SEO/브랜딩에 유리
    • 단점: 로컬/프리뷰/운영 환경별 DNS/호스트 처리 고려 필요

  • 경로 기반: example.com/tenant-a/*

    • 장점: DNS가 단순
    • 단점: 라우팅/SEO/권한/캐시 정책이 복잡해질 수 있음

3.2 Middleware로 라우팅 “결정”을 앞단에서 처리

멀티테넌트에서는 요청이 들어오면 다음을 결정해야 합니다.

  • 어떤 테넌트인가?
  • 랜딩(메인 도메인) 요청인가, 테넌트 도메인 요청인가?
  • /admin 같은 공용 경로인가?

예제는 “서브도메인을 감지 → 테넌트 페이지로 라우팅”을 Middleware로 처리합니다.

3.3 데이터 분리 전략

필수 질문:

  • 테넌트별 DB 분리인가? (DB/스키마/row-level)
  • 공용 DB + 테넌트 키 분리인가?
  • 캐시/세션/스토리지 키 네임스페이스를 어떻게 보장할 것인가?

예제는 Redis 키 패턴으로 subdomain:{name} 형태를 사용한다고 안내합니다.

3.4 로컬/프리뷰/운영 환경을 모두 고려

서브도메인 기반은 특히 다음이 중요합니다.

  • 로컬에서 tenant.localhost 형태 테스트 지원
  • Vercel Preview 도메인에서 서브도메인 감지 규칙
  • 운영에서 *.yourdomain.com 와일드카드 DNS 설정

예제는 와일드카드 DNS(*.yourdomain.com) 설정을 포함해 Vercel 배포 흐름까지 안내합니다.

4. 빠른 시작(추천)

  • 멀티테넌트를 “처음부터” 직접 설계하기보다, 공식 예제(Starter Kit)를 먼저 실행해 보고
  • 자신의 서비스 요구사항에 맞게
    • 테넌트 저장소(DB/Redis)
    • 인증/권한
    • 테넌트 생성/관리 UX
    • SEO/메타데이터 전략 을 확장하는 접근이 가장 안전합니다.