내가 AI SaaS 스타터 키트를 만든 이유 — 그리고 설정에 40시간을 절약하는 방법

Source: Dev.to

대부분의 SaaS 스타터는 골격만 제공합니다. 여전히 뼈대를 연결하는 데 40 시간을 소비합니다.

그 40 시간이 실제로 어떻게 보이는지, 그리고 제가 그것을 어떻게 없앴는지 살펴보세요.

40시간 인벤토리

이것들은 제품 작업이 아닙니다. 모든 SaaS가 필요로 하는 기본 인프라일 뿐입니다. 그리고 이것은 해결되었습니다 — 각각을 올바르게 수행하는 방법이 있으며, 몇 번 해보면 복잡하지 않습니다.

문제는 “몇 번 해보면”이라는 점입니다 — 처음은 느리고, 솔루션들이 함께 설계되지 않으면 깔끔하게 결합되지 않으며, 가장자리 경우들 (Stripe 웹훅 서명 검증, 비밀번호 변경 시 세션 무효화, 결제 실패 시 점진적 감소) 은 시간 압박 속에서 놓치기 쉽습니다.

실제 스타터에 포함되어야 할 것

많은 스타터를 살펴봤습니다. 대부분은 체크리스트를 만족하지만 실제로 바로 동작하지는 않아요—항상 빠진 단계가 있거나, 호환되지 않는 버전이 있거나, 모의(mock)만 되고 구현되지 않은 기능이 있습니다. 제가 생각하는 “프로덕션 준비 완료”는 다음과 같습니다:

실제로 동작하는 인증

• 적절한 bcrypt 해싱을 적용한 이메일/비밀번호
• Google 및 GitHub OAuth
• 옵션으로 제공되는 매직 링크
• 적절한 만료와 회전을 지원하는 세션 관리
• 미들웨어 수준에서 강제되는 역할 기반 접근 제어(관리자 vs. 사용자), UI에만 국한되지 않음
• 시간 제한이 있는 토큰을 이용한 비밀번호 재설정

실제 시나리오를 처리하는 Stripe

• 제품 및 가격 생성
• 구독 라이프사이클: trial → active → past_due → canceled
• 멱등성을 고려한 웹훅 처리(중요—Stripe는 재시도함)
• 셀프 서비스 청구 관리를 위한 고객 포털
• 사용량 기반 청구 옵션
• 플랜 한도에 도달했을 때 우아하게 감소하는 메터링 기능

확장 가능한 데이터베이스

• 적절한 관계를 정의한 Prisma 스키마
• db push만이 아닌 마이그레이션 전략
• 서버리스 환경을 위한 커넥션 풀링 설정
• 필요에 따라 소프트 삭제 적용
• 청구와 관련된 중요한 작업을 기록하는 감사 로그 테이블

실제로 배포 가능한 대시보드

• 반응형 사이드바 + 탑바 레이아웃
• shadcn/ui 컴포넌트가 이미 통합된 상태
• 다크 모드 지원
• 모든 페이지에 로딩 상태와 에러 경계 구현
• 페이지네이션, 정렬, 필터링이 가능한 테이블 컴포넌트

대부분의 초보자들이 놓치는 핵심 요소

1. Webhook 멱등성
   Stripe는 동일한 웹훅을 두 번 전송할 수 있습니다. 핸들러가 customer.subscription.created 이벤트에서 구독 레코드를 생성한다면 중복 레코드가 생깁니다. 해결 방법은 Stripe 이벤트 ID에 고유 제약 조건을 둔 processed_events 테이블을 두는 것입니다. 대부분의 초보자는 이를 포함하지 않습니다.

2. UX를 깨뜨리지 않는 플랜 강제 적용
   사용자가 플랜 한도에 도달했을 때는 명확한 업그레이드 프롬프트가 보여야 합니다—500 오류나 무음 실패가 아니라. 이를 위해서는 기능 코드와 플랜 체크 사이에, 부드럽게 다운그레이드하는 방법을 알고 있는 레이어가 필요합니다. 나중에 추가하기는 어렵고, 처음부터 설계하는 것이 쉽습니다.

3. 체험‑유료 전환 흐름
   체험 기간은 자체 상태 머신이 필요합니다: trial_start, trial_active, trial_ending_soon(남은 3일에 이메일 발송), trial_ended_active(유료 전환), trial_ended_canceled(이탈). 대부분의 초보자는 체험을 Stripe 기능으로만 취급하고 제품 측면을 모델링하지 않습니다.

4. 팀/조직 지원
   단일 사용자 SaaS는 시작하기에 괜찮지만, 향후 팀을 지원하려면 데이터 모델을 처음부터 올바르게 설계해야 합니다. 나중에 사용자 중심 모델에 teams 테이블을 추가하는 것은 고통스럽습니다. 스타터에는 필요할 때까지 무시할 수 있는 선택적 멀티‑테넌트 구조가 포함되어 있어야 합니다.

현재 설정

제가 만든 AI SaaS Starter Kit 은 위 모든 것을 처리합니다. Next.js 14 App Router 프로젝트이며 다음을 포함합니다:

• NextAuth v5 — 이메일/비밀번호, Google, GitHub, 매직 링크
• Stripe — 구독, 일회성 결제, 사용량 측정, 고객 포털
• Prisma + PostgreSQL — 사용자, 팀, 구독, 감사 로그 스키마
• shadcn/ui — 전체 컴포넌트 라이브러리 설치 및 구성
• Resend — React Email 템플릿을 이용한 트랜잭션 이메일
• Vercel — 환경 변수 문서가 포함된 배포 설정
• Claude API routes — 스트리밍 응답 및 도구 사용을 위한 사전 구축 패턴

모든 것이 서로 연결됩니다. 인증 세션은 구독 상태를 알고, 미들웨어는 플랜 제한을 적용하며, 웹훅은 데이터베이스를 업데이트하고 이메일을 트리거합니다. 대시보드는 실제 데이터를 표시합니다.

복제하고 환경 변수(.env.example에 문서화됨)를 추가한 뒤 실행합니다:

npm install && npm run dev

누락된 부분이 없습니다.

40시간이 사는 것

저는 하나를 설정하는 데 걸리던 시간에 세 개의 제품을 출시했습니다. 인프라 결정은 이미 내려졌고 전투 테스트를 거쳤습니다. 엣지 케이스도 처리되었습니다. 패턴은 코드베이스 전반에 걸쳐 일관됩니다.

절약한 40시간은 단순히 시간만이 아니라, 설정 작업에 지쳐 실제 만들고 싶었던 제품을 출시하고 싶을 때 겪는 40시간의 좌절, 컨텍스트 전환, 디버깅을 의미합니다.

제품을 출시하세요. 골조가 아니라.

The AI SaaS Starter Kit is a one‑time purchase at … (price/details to be added)

• $99 – 전체 소스 코드를 라이선스 제한 없이 제공합니다 — 수정하고, 확장하고, 자신의 제품으로 출시할 수 있습니다.