v0에서 Shadcn UI, API 라우트 핸들러, Vercel 원클릭 배포로 멀티페이지 SaaS 대시보드 만들기
v0로 멀티페이지 SaaS 대시보드를 구축하는 완벽 가이드
v0는 Vercel이 제공하는 AI 기반 UI 생성 도구로, 프롬프트만으로 완전한 React 컴포넌트와 페이지를 생성할 수 있습니다. 이 가이드에서는 v0를 활용하여 Shadcn UI 기반의 멀티페이지 SaaS 대시보드를 설계하고, API 라우트 핸들러를 구성한 뒤, Vercel에 원클릭 배포하는 전체 워크플로우를 단계별로 안내합니다.
사전 준비 사항
- Node.js 18 이상 설치- Vercel 계정 (vercel.com)- v0 접근 권한 (v0.dev)- Git 및 GitHub 계정
단계 1: v0에서 대시보드 레이아웃 생성
v0.dev에 접속한 후, 프롬프트를 입력하여 대시보드의 기본 레이아웃을 생성합니다.
프롬프트 예시
Build a multi-page SaaS dashboard with:
- Sidebar navigation (Dashboard, Analytics, Users, Settings)
- Top header with user avatar and notification bell
- Dashboard page with KPI cards, line chart, and recent activity table
- Use Shadcn UI components with dark mode support
Responsive layout for mobile and desktopv0가 생성한 코드를 확인한 후 “Add to Codebase” 버튼을 클릭하면 프로젝트에 직접 통합할 수 있습니다.
단계 2: 로컬 프로젝트 초기화 및 Shadcn UI 설치
v0에서 생성한 코드를 로컬 환경에서 확장하려면 Next.js 프로젝트를 설정합니다.
npx create-next-app@latest saas-dashboard —typescript —tailwind —eslint —app —src-dir
cd saas-dashboard
npx shadcn@latest init
Shadcn UI 초기화 시 설정 옵션:
✔ Which style would you like to use? › New York
✔ Which color would you like to use as base color? › Slate
✔ Would you like to use CSS variables for colors? › yes
필수 컴포넌트 설치
npx shadcn@latest add card button table tabs avatar badge separator
npx shadcn@latest add sidebar navigation-menu dropdown-menu
npx shadcn@latest add chart단계 3: 멀티페이지 라우팅 구조 설정
Next.js App Router를 사용하여 페이지 구조를 생성합니다.
src/app/
├── layout.tsx # 전역 레이아웃 (사이드바 포함)
├── page.tsx # 대시보드 홈
├── analytics/
│ └── page.tsx # 분석 페이지
├── users/
│ └── page.tsx # 사용자 관리
├── settings/
│ └── page.tsx # 설정 페이지
└── api/
├── analytics/
│ └── route.ts # 분석 데이터 API
└── users/
└── route.ts # 사용자 데이터 API
## 단계 4: API 라우트 핸들러 구현
Next.js의 Route Handler를 사용하여 백엔드 API를 구성합니다.
분석 데이터 API (src/app/api/analytics/route.ts)
import { NextResponse } from “next/server”;
const API_KEY = process.env.ANALYTICS_API_KEY; // YOUR_API_KEY
export async function GET(request: Request) {
const { searchParams } = new URL(request.url);
const period = searchParams.get(“period”) || “7d”;
try {
const response = await fetch(
https://api.example.com/v1/analytics?period=${period},
{
headers: {
Authorization: Bearer ${API_KEY},
“Content-Type”: “application/json”,
},
next: { revalidate: 300 }, // 5분 캐시
}
);
const data = await response.json();
return NextResponse.json(data);
} catch (error) {
return NextResponse.json(
{ error: “데이터를 불러올 수 없습니다” },
{ status: 500 }
);
}
}
사용자 관리 API (src/app/api/users/route.ts)
import { NextResponse } from "next/server";
export async function GET() {
const users = await fetch("https://api.example.com/v1/users", {
headers: { Authorization: `Bearer ${process.env.DB_API_KEY}` },
});
return NextResponse.json(await users.json());
}
export async function POST(request: Request) {
const body = await request.json();
const result = await fetch("https://api.example.com/v1/users", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DB_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify(body),
});
return NextResponse.json(await result.json(), { status: 201 });
}단계 5: 대시보드 페이지에서 API 연동
// src/app/page.tsx
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
async function getAnalytics() {
const res = await fetch(`${process.env.NEXT_PUBLIC_BASE_URL}/api/analytics?period=30d`, {
cache: "no-store",
});
return res.json();
}
export default async function DashboardPage() {
const analytics = await getAnalytics();
return (
총 매출
{analytics.revenue?.toLocaleString()}원
);
}단계 6: 환경 변수 설정
프로젝트 루트에 .env.local 파일을 생성합니다.
ANALYTICS_API_KEY=YOUR_API_KEY
DB_API_KEY=YOUR_API_KEY
NEXT_PUBLIC_BASE_URL=http://localhost:3000
## 단계 7: Vercel 원클릭 배포
- GitHub에 코드를 푸시합니다.- [vercel.com/new](https://vercel.com/new)에서 리포지토리를 연결합니다.- 환경 변수를 Vercel 대시보드에서 설정합니다.- **Deploy** 버튼을 클릭합니다.
# CLI를 통한 배포도 가능합니다
npm i -g vercel
vercel login
vercel --prodVercel CLI로 환경 변수를 설정하려면:
vercel env add ANALYTICS_API_KEY production
vercel env add DB_API_KEY production
## Pro Tips: 파워 유저를 위한 고급 팁
- **v0 프롬프트 체이닝:** 기본 레이아웃을 먼저 생성한 뒤, 개별 페이지를 별도 프롬프트로 세분화하여 생성하면 더 정교한 결과를 얻을 수 있습니다.- **반복 수정 활용:** v0의 대화형 인터페이스에서 "이 카드에 스파크라인 차트를 추가해줘"처럼 점진적으로 수정 요청을 하세요.- **미들웨어로 인증 보호:** src/middleware.ts에 인증 로직을 추가하여 대시보드 전체를 보호하세요.- **ISR 활용:** 분석 페이지에 revalidate를 설정하면 서버 부하 없이 최신 데이터를 제공할 수 있습니다.- **Vercel Analytics 통합:** @vercel/analytics 패키지를 추가하면 실제 사용자 행동 데이터를 수집할 수 있습니다.
## Troubleshooting: 자주 발생하는 오류 해결
| 오류 | 원인 | 해결 방법 |
|---|---|---|
Module not found: @/components/ui/card | Shadcn 컴포넌트 미설치 | npx shadcn@latest add card 실행 |
NEXT_PUBLIC_BASE_URL undefined | 환경 변수 미설정 | .env.local 파일 확인 후 서버 재시작 |
Hydration mismatch | 서버/클라이언트 렌더링 불일치 | 동적 데이터에 "use client" 지시문 추가 |
| Vercel 배포 시 API 오류 | 환경 변수 미등록 | Vercel 대시보드 → Settings → Environment Variables 확인 |
TypeError: fetch failed | API 엔드포인트 오류 또는 네트워크 문제 | API URL 확인 및 서버 로그 점검 |
Q1: v0에서 생성한 코드를 직접 수정할 수 있나요?
네, v0에서 생성된 코드는 일반 React/Next.js 코드이므로 자유롭게 수정할 수 있습니다. "Add to Codebase" 기능을 통해 로컬 프로젝트에 통합한 뒤, 컴포넌트 구조나 스타일을 원하는 대로 커스터마이즈할 수 있습니다. v0는 초기 코드 생성을 가속화하는 도구이며, 최종 코드의 소유권은 개발자에게 있습니다.
Q2: Shadcn UI 컴포넌트를 v0 프롬프트에서 직접 지정할 수 있나요?
네, v0는 Shadcn UI를 기본 컴포넌트 라이브러리로 사용합니다. 프롬프트에 “Shadcn Card 컴포넌트를 사용해서 KPI 카드를 만들어줘”처럼 구체적인 컴포넌트명을 명시하면 해당 컴포넌트를 정확하게 활용한 코드를 생성합니다. Table, Chart, Dialog 등 다양한 Shadcn UI 컴포넌트를 지정할 수 있습니다.
Q3: API Route Handler에서 데이터베이스에 직접 연결할 수 있나요?
네, Next.js API Route Handler에서 Prisma, Drizzle 같은 ORM을 사용하여 데이터베이스에 직접 연결할 수 있습니다. Vercel에 배포할 경우 Vercel Postgres, PlanetScale, Supabase 등 서버리스 환경에 최적화된 데이터베이스 서비스를 권장합니다. 연결 문자열은 반드시 환경 변수로 관리하세요.