메인 콘텐츠로 건너뛰기

​
개요

Next.js 최소 보일러플레이트는 Dodo Payments를 Next.js 애플리케이션에 통합하기 위한 즉시 사용 가능한 시작점을 제공합니다. 이 템플릿에는 체크아웃 세션, 웹훅 처리, 고객 포털 및 현대적인 UI 구성 요소가 포함되어 있어 빠르게 결제를 수락할 수 있도록 도와줍니다.
이 보일러플레이트는 TypeScript, Tailwind CSS 4 및 @dodopayments/nextjs 어댑터와 함께 Next.js 16 앱 라우터를 사용합니다.

​
기능

  • 빠른 설정 - 5분 이내에 시작
  • 결제 통합 - @dodopayments/nextjs를 사용한 사전 구성된 체크아웃 흐름
  • 현대적인 UI - Tailwind CSS로 깔끔하고 어두운 테마의 가격 페이지
  • 웹훅 핸들러 - 결제 이벤트를 위한 즉시 사용 가능한 웹훅 엔드포인트
  • 고객 포털 - 원클릭 구독 관리
  • TypeScript - 최소한의 집중된 타입으로 완전히 타입 지정됨
  • 사전 채워진 체크아웃 - UX 개선을 위한 고객 데이터 전달 시연

​
필수 조건

시작하기 전에 다음을 확인하세요:
  • Node.js 20.9+ (Next.js 16에 필요)
  • Dodo Payments 계정 (대시보드에서 API 및 웹훅 키에 접근하기 위해)

​
빠른 시작

1

레포지토리 복제

git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
cd dodo-nextjs-minimal-boilerplate
2

의존성 설치

npm install
3

API 자격 증명 받기

Dodo Payments에 가입하고 대시보드에서 자격 증명을 받으세요:
개발 중에는 테스트 모드에 있는지 확인하세요!
4

환경 변수 구성

루트 디렉토리에 .env 파일을 생성하세요:
cp .env.example .env
Dodo Payments 자격 증명으로 값을 업데이트하세요:
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_RETURN_URL=http://localhost:3000
DODO_PAYMENTS_ENVIRONMENT=test_mode
.env 파일을 버전 관리에 커밋하지 마세요. 이미 .gitignore에 포함되어 있습니다.
5

제품 추가

Dodo Payments에서 실제 제품 ID로 src/lib/products.ts을 업데이트하세요:
export const products: Product[] = [
  {
    product_id: "pdt_001", // Replace with your product ID
    name: "Basic Plan",
    description: "Get access to basic features and support",
    price: 9999, // in cents
    features: [
      "Access to basic features",
      "Email support",
      "1 Team member",
      "Basic analytics",
    ],
  },
  // ... add more products
];
6

개발 서버 실행

npm run dev
http://localhost:3000을 열어 가격 페이지를 확인하세요!

​
프로젝트 구조

src/
├── app/
│   ├── api/
│   │   ├── checkout/          # Checkout session handler
│   │   ├── customer-portal/   # Customer portal redirect
│   │   └── webhook/           # Webhook event handler
│   ├── components/
│   │   ├── Footer.tsx         # Reusable footer
│   │   ├── Header.tsx         # Navigation header
│   │   └── ProductCard.tsx    # Product pricing card
│   ├── globals.css            # Global styles
│   ├── layout.tsx             # Root layout
│   └── page.tsx               # Pricing page (home)
└── lib/
    └── products.ts            # Product definitions

​
사용자 정의

​
제품 정보 업데이트

src/lib/products.ts을 편집하여 다음을 수정하세요:
  • 제품 ID (Dodo 대시보드에서)
  • 가격
  • 기능
  • 설명

​
고객 데이터 사전 채우기

src/app/components/ProductCard.tsx에서 하드코딩된 값을 실제 사용자 데이터로 교체하세요: 
customer: {
  name: "John Doe",
  email: "[email protected]",
},

​
고객 포털 업데이트

src/app/components/Header.tsx에서 하드코딩된 고객 ID를 교체하세요: 
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
테스트를 위해 고객 ID를 얻기 위해 테스트 구매를 완료할 수 있습니다.

​
웹훅 이벤트

이 보일러플레이트는 src/app/api/webhook/route.ts에서 두 개의 웹훅 이벤트를 처리하는 방법을 보여줍니다:
  • onSubscriptionActive - 구독이 활성화될 때 트리거됨
  • onPaymentSucceeded - 결제가 성공할 때 트리거됨
이 핸들러 내에 비즈니스 로직을 추가하세요: 
onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},
필요에 따라 더 많은 웹훅 이벤트를 추가하세요. 로컬 개발을 위해 ngrok와 같은 도구를 사용하여 로컬 서버에 대한 보안 터널을 생성하고 이를 웹훅 URL로 사용할 수 있습니다.

​
배포

​
프로덕션 빌드

npm run build
npm start

​
Vercel에 배포

[ Vercel로 배포 ](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) Vercel 대시보드에 환경 변수를 추가하는 것을 잊지 마세요!

​
웹훅 URL 업데이트

배포 후, Dodo Payments 대시보드에서 웹훅 URL을 업데이트하세요: 
https://example.com/api/webhook

​
문제 해결

node_modules를 삭제하고 의존성을 재설치하세요:
rm -rf node_modules package-lock.json
npm install
일반적인 원인:
  • 유효하지 않은 제품 ID - Dodo 대시보드에서 존재하는지 확인하세요
  • .env에서 잘못된 API 키 또는 환경 설정
  • 오류에 대한 브라우저 콘솔 및 터미널 확인
로컬 테스트를 위해 ngrok을 사용하여 서버를 노출하세요:
ngrok http 3000
웹훅 URL을 ngrok URL로 Dodo 대시보드(Dodo 대시보드)에서 업데이트하세요. 올바른 웹훅 검증 키로 .env 파일을 업데이트하는 것을 잊지 마세요.
하드코딩된 CUSTOMER_ID를 src/app/components/Header.tsx에서 Dodo 대시보드의 실제 고객 ID로 교체하세요.또는 인증 시스템과 데이터베이스를 통합하여 고객 ID를 동적으로 가져올 수 있습니다.

​
더 알아보기

​
지원

보일러플레이트에 대한 도움이 필요하신가요?