OneSaaS Starter

AI와 함께 개발하는 한국형 SaaS 템플릿

Next.js 16 + Supabase + Tailwind CSS 기반의 SaaS 스타터 킷입니다. K-Code AI 코딩 도구가 내장되어 있어 한국어로 자연스럽게 개발할 수 있습니다.

빠른 시작

# 1. 템플릿 다운로드
git clone https://github.com/johunsang/onesass-starter.git my-saas
cd my-saas

# 2. 의존성 설치 (자동으로 안내 메시지 표시)
pnpm install

# 3. 설정 마법사 실행 ⭐ (단계별 안내)
pnpm setup

pnpm setup 하나로 끝! 마법사가 단계별로 안내해줍니다:

자동 설정 (추천): Access Token만 입력하면 프로젝트 선택 → 자동 완성!
수동 설정: 직접 환경변수를 입력하고 싶다면 이 옵션
Supabase 없으면? → 만드는 방법 상세 안내
DB 스키마 적용 → 자동 실행 옵션
개발 서버 실행 → 자동 실행 옵션

💡 Supabase가 뭔가요? 무료 데이터베이스 서비스예요. https://supabase.com 에서 2분이면 만들 수 있어요. pnpm setup 실행하면 만드는 방법도 알려줍니다!

Supabase 자동 설정 (추천)

Access Token 하나로 모든 환경변수가 자동 설정됩니다!

pnpm setup
# → "Access Token으로 자동 설정" 선택
# → Access Token 입력 (supabase.com/dashboard/account/tokens에서 발급)
# → 프로젝트 선택
# → DB 비밀번호 입력
# → 완료! 🎉

자동 설정되는 항목	설명
DATABASE_URL	데이터베이스 연결 URL
NEXT_PUBLIC_SUPABASE_URL	Supabase 프로젝트 URL
NEXT_PUBLIC_SUPABASE_ANON_KEY	공개 API 키

http://localhost:3000 에서 확인

🚨 OneSaaS로 배포한 후 로컬 개발 (필수!)

OneSaaS 빌더(onesaas.kr)로 이미 배포했다면 이 방법을 사용하세요!

OneSaaS로 배포한 프로젝트를 로컬에서 개발하려면 환경변수가 필요합니다. Vercel CLI 명령어 하나로 모든 환경변수를 가져올 수 있습니다.

사전 준비사항

1. Node.js 20.9.0 이상 필요

# 버전 확인
node -v

# 20.9.0 미만이면 업데이트 필요
# Windows: https://nodejs.org 에서 LTS 버전 다운로드
# Mac: nvm install 20 && nvm use 20

2. pnpm 설치 (선택사항, npm도 가능)

npm install -g pnpm

3. Private 리포지토리 접근을 위한 GitHub 인증

방법 1: GitHub CLI 사용 (권장)

# Windows
winget install --id GitHub.cli

# Mac
brew install gh

# 로그인
gh auth login

방법 2: ZIP 파일 다운로드

OneSaaS 배포 완료 페이지에서 "📦 ZIP 파일로 다운로드" 버튼 클릭

설치 단계

# 1. 프로젝트 클론 (또는 ZIP 다운로드 후 압축 해제)
git clone https://github.com/내계정/내프로젝트.git
cd 내프로젝트

# 2. 의존성 설치
pnpm install
# 또는 npm install

# 3. Vercel CLI 설치 (처음 한 번만)
npm install -g vercel

# 4. Vercel 프로젝트 연결 (처음 한 번만)
vercel link
# 또는 Windows에서 에러 시: npx vercel link

# 5. 환경변수 가져오기 (.env.local 자동 생성!)
vercel env pull .env.local
# 또는 Windows에서 에러 시: npx vercel env pull .env.local

# 6. 개발 서버 실행
pnpm dev

Windows 사용자 주의사항

PowerShell에서 vercel 명령어 에러:

vercel 명령어를 찾을 수 없다는 에러가 나면:

해결 방법 1: PowerShell 재시작 (가장 쉬움) 해결 방법 2: npx 사용 (권장)

npx vercel link
npx vercel env pull .env.local

Windows ARM64 (Surface Pro X 등) SWC 에러:

"Failed to load SWC binary" 에러가 나면 .env.local 파일에 추가:

NEXT_DISABLE_SWC=1

왜 이게 필요한가요?

배포 시 자동 생성된 중요한 설정값들:

DATABASE_URL - 24자리 랜덤 비밀번호가 포함된 DB 연결 주소
SUPABASE_URL/KEY - 인증 시스템 연결 정보
결제 API 키 - 결제 시스템 연결 정보

이 모든 값이 Vercel에 안전하게 저장되어 있어서, vercel env pull 명령어로 한 번에 가져옵니다!

💡 pnpm setup과 뭐가 다른가요?

pnpm setup: 처음 템플릿을 클론해서 새 프로젝트를 만들 때

vercel env pull: OneSaaS로 이미 배포한 프로젝트를 로컬에서 개발할 때

소셜 로그인 설정

OneSaaS는 이메일, Google, 카카오, GitHub 로그인을 지원합니다.

이메일 로그인 (기본 제공)

이메일 로그인은 별도 설정 없이 바로 사용 가능합니다.

pnpm setup 완료 후 바로 이메일로 회원가입/로그인할 수 있습니다.

소셜 로그인 (OAuth)

Google, 카카오, GitHub 로그인을 사용하려면 추가 설정이 필요합니다.

상세 가이드: OAUTH-SETUP.md 문서를 참고하세요.

간단 요약:

Google: Google Cloud Console에서 OAuth 클라이언트 생성
카카오: 카카오 Developers에서 앱 생성
GitHub: GitHub에서 OAuth App 생성
Supabase에 각 OAuth 정보 등록

로그인 제공자 선택

onesaas.json 파일에서 사용할 로그인 방법을 선택할 수 있습니다:

{
  "features": {
    "auth": {
      "enabled": true,
      "providers": ["email", "google", "kakao", "github"]
    }
  }
}

K-Code: AI 코딩 어시스턴트

이 템플릿에는 K-Code가 내장되어 있습니다. 한국어로 코딩 작업을 요청하세요!

사용법

# 기본 사용 - 한국어로 말하면 끝!
pnpm kcode "로그인 페이지에 유효성 검사 추가해줘"

# 대화형 모드 - AI와 실시간 대화
pnpm kcode -i

# 복잡한 작업 - 개발 모드
pnpm kcode --dev "인증 시스템 리팩토링해줘"

# 모델 선택
pnpm kcode -m deepseek "버그 수정해줘"

지원 AI 모델 (가격순)

모델	가격 (1M 토큰)	특징
Qwen Turbo	$0.03	💰 가장 저렴!
MiniMax M2.1	$0.07	코딩 특화
Groq Qwen3	$0.24	⚡ 초고속, 무료 티어
DeepSeek V3.2	$0.27	🔧 코딩 구현
Gemini 3 Flash	$0.50	🌟 이미지 분석

API 키 설정

# Groq (무료 티어 있음, 추천)
pnpm kcode --key groq YOUR_GROQ_API_KEY

# Qwen (가장 저렴)
pnpm kcode --key qwen YOUR_QWEN_API_KEY

# DeepSeek (코딩 특화)
pnpm kcode --key deepseek YOUR_DEEPSEEK_API_KEY

# 모델 목록 보기
pnpm kcode --list

💡 어떤 API 키를 써야 하나요? 처음이라면 Groq 추천! 무료 티어가 있어서 테스트하기 좋아요. https://console.groq.com 에서 가입하고 API 키 발급받으세요.

원스탑 가이드

1. 코드 수정

pnpm dev                    # 개발 서버 실행
# src/onesaas-custom/ 에서 자유롭게 수정

2. Git 커밋

git add .
git commit -m "feat: 새 기능 추가"
git push                    # 자동 배포!

3. 배포

Git push하면 Vercel이 자동으로 배포합니다.

4. DB 변경

pnpm db:push                # 개발용
pnpm db:migrate             # 프로덕션용

포함된 기능

기능	설명
OAuth 자동 설정 🆕	OneSaaS 빌더 사용 시 Google/Kakao/GitHub 로그인 자동 연동
인증	이메일, Google, 카카오, GitHub 로그인
결제	Toss Payments, TossPayments 연동 (한국형)
관리자	대시보드, 사용자 관리, 통계, Chart.js
AI 기능	AI 글쓰기, 이미지 생성 샘플
테마	11개 테마 + 다크/라이트 모드
K-Code	한국어 AI 코딩 어시스턴트

샘플 페이지

페이지	경로	설명
홈	`/`	랜딩 페이지
로그인	`/login`	로그인 샘플
회원가입	`/signup`	회원가입 샘플
대시보드	`/dashboard`	사용자 대시보드
AI 도구	`/dashboard/ai`	AI 기능 샘플
관리자	`/admin`	관리자 대시보드
사용자 관리	`/admin/users`	사용자 CRUD
결제 관리	`/admin/payments`	결제 내역
통계	`/admin/analytics`	통계 차트
쇼케이스	`/showcase`	UI 컴포넌트

환경 변수

💡 직접 설정하지 마세요! pnpm setup 실행하면 알아서 만들어줍니다.

수동으로 설정하려면 .env 파일:

# Supabase (필수) - pnpm setup이 안내해줌
# Connection Pooler 사용 (포트 6543 + pgbouncer)
DATABASE_URL=postgresql://postgres.xxx:비밀번호@aws-0-ap-northeast-2.pooler.supabase.com:6543/postgres?pgbouncer=true
DIRECT_URL=postgresql://postgres.xxx:비밀번호@aws-0-ap-northeast-2.pooler.supabase.com:5432/postgres
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...

# K-Code AI (선택) - pnpm kcode --key 명령어로 설정
GROQ_API_KEY=gsk_...             # 무료 티어 있음
QWEN_API_KEY=sk-...              # 가장 저렴
DEEPSEEK_API_KEY=sk-...          # 코딩 특화

# 결제 (선택)
NEXT_PUBLIC_TOSS_MERCHANT_ID=imp...
NEXT_PUBLIC_TOSS_CLIENT_KEY=test_ck_...

스크립트

# 처음 시작할 때
pnpm setup            # ⭐ 설정 마법사 (이것만 하면 됨!)

# 개발
pnpm dev              # 개발 서버
pnpm build            # 프로덕션 빌드

# 데이터베이스
pnpm db:push          # DB 스키마 적용
pnpm db:studio        # DB 보기 (브라우저에서)

# K-Code AI
pnpm kcode "작업"     # AI에게 코딩 시키기
pnpm kcode -i         # AI와 대화형 코딩
pnpm kcode --list     # 모델 목록 보기

폴더 구조

my-saas/
├── src/
│   ├── app/                    # Next.js App Router
│   ├── onesaas-core/           # 핵심 모듈
│   │   ├── admin/              # 관리자 기능
│   │   ├── auth/               # 인증
│   │   ├── payment/            # 결제
│   │   ├── themes/             # 테마
│   │   └── ui/                 # UI 컴포넌트
│   ├── onesaas-custom/         # 커스텀 코드 (자유롭게 수정)
│   ├── onesaas-managed/        # 관리 코드
│   └── onesaas-bridge/         # 설정 연결
├── cli/                        # K-Code CLI 소스
├── cli-dist/                   # K-Code 빌드 결과
├── prisma/                     # DB 스키마
└── public/                     # 정적 파일

배포

Vercel (권장)

Git push하면 자동 배포됩니다!

수동 배포

pnpm build
# .next 폴더를 Vercel/AWS/GCP에 배포

기술 스택

프레임워크: Next.js 16 (App Router)
스타일: Tailwind CSS
데이터베이스: Prisma + Supabase (PostgreSQL)
인증: Supabase Auth
결제: Toss Payments / TossPayments
차트: Chart.js
AI 코딩: K-Code (DeepSeek, OpenAI, Anthropic)
AI SDK: Vercel AI SDK

문서

주요 가이드

OAuth 설정 가이드: OAUTH-SETUP.md - Google, 카카오, GitHub 소셜 로그인 설정 방법
개발 가이드: CLAUDE.md - 프로젝트 개발 가이드
배포 가이드: DEPLOYMENT.md - Vercel 배포 가이드
유지보수 가이드: MAINTENANCE.md - 프로젝트 유지보수 방법

링크

OneSaaS 빌더: https://onesaas.kr
GitHub: https://github.com/johunsang/onesass-starter
K-Code 문서: https://onesaas.kr/docs/kcode

라이선스

MIT

Name		Name	Last commit message	Last commit date
.claude		.claude
.kcode		.kcode
prisma		prisma
public		public
scripts		scripts
src		src
.env.example		.env.example
.env.example.bak		.env.example.bak
.gitignore		.gitignore
BUILDER-INTEGRATION-TEST.md		BUILDER-INTEGRATION-TEST.md
CLAUDE.md		CLAUDE.md
CLAUDE.md.bak		CLAUDE.md.bak
DEPLOYMENT.md		DEPLOYMENT.md
DEPLOYMENT.md.bak		DEPLOYMENT.md.bak
DETAILED_TEST_REPORT.md		DETAILED_TEST_REPORT.md
INTEGRATION_TEST_REPORT.md		INTEGRATION_TEST_REPORT.md
MAINTENANCE.md		MAINTENANCE.md
OAUTH-SETUP.md		OAUTH-SETUP.md
README.md		README.md
README.md.bak		README.md.bak
TEST-REPORT.md		TEST-REPORT.md
TESTING_REPORT.md		TESTING_REPORT.md
fix-prisma-arm64.bat		fix-prisma-arm64.bat
next.config.mjs		next.config.mjs
onesaas.json		onesaas.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Latest commit

History

Folders and files

Repository files navigation