Next.js Minimal Boilerplate

개요

Next.js 최소 보일러플레이트는 Dodo Payments을(를) Next.js 애플리케이션에 통합할 수 있도록 바로 사용할 수 있는 시작점을 제공합니다. 이 템플릿에는 Checkout Sessions, webhook 처리, Customer Portal 및 최신 UI 컴포넌트가 포함되어 있어 빠르게 결제를 받기 시작할 수 있습니다.

이 보일러플레이트는 TypeScript, Tailwind CSS 4 및 @dodopayments/nextjs adapter를 사용하는 Next.js 16 App Router를 기반으로 합니다.

기능

빠른 설정 - 5분 이내에 시작
결제 통합 - @dodopayments/nextjs를 사용하는 사전 구성된 checkout flow
최신 UI - Tailwind CSS를 사용한 깔끔한 다크 테마 pricing page
Webhook Handler - 결제 이벤트를 위한 바로 사용 가능한 webhook endpoint
Customer Portal - 한 번의 클릭으로 subscription 관리
TypeScript - 최소한의 집중된 types로 완전한 type 지원
사전 입력된 Checkout - UX 개선을 위해 customer data를 전달하는 방법을 보여줌

사전 요구 사항

시작하기 전에 다음을 준비하세요:

Node.js 20.9+ (Next.js 16에 필요)
Dodo Payments account (dashboard에서 API 및 Webhook Keys에 액세스하기 위해 필요)

빠른 시작

Clone the Repository

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

Install Dependencies

npm install

Get API Credentials

Dodo Payments에서 가입하고 dashboard에서 credentials를 확인하세요:

API Key: Dashboard → Developer → API Keys
Webhook Key: Dashboard → Developer → Webhooks

개발하는 동안 Test Mode인지 확인하세요!

Configure Environment Variables

루트 디렉터리에 .env 파일을 생성하세요:

cp .env.example .env

Dodo Payments credentials로 값을 업데이트하세요:

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 파일을 version control에 커밋하지 마세요. 이 파일은 이미 .gitignore에 포함되어 있습니다.

Add Your Products

src/lib/products.ts를 Dodo Payments의 실제 product IDs로 업데이트하세요:

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
];

Run the Development Server

npm run dev

http://localhost:3000을 열어 pricing page를 확인하세요!

프로젝트 구조

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

사용자 지정

Product Information 업데이트

src/lib/products.ts를 편집하여 다음을 수정하세요:

Product IDs (사용자의 Dodo dashboard에서 확인)
Pricing
Features
Descriptions

Customer Data 사전 입력

src/app/components/ProductCard.tsx에서 하드코딩된 값을 실제 user data로 바꾸세요:

customer: {
  name: "John Doe",
  email: "john@example.com",
},

Customer Portal 업데이트

src/app/components/Header.tsx에서 하드코딩된 customer ID를 바꾸세요:

const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID

테스트 구매를 완료하여 테스트에 사용할 customer ID를 가져올 수 있습니다.

Webhook Events

이 보일러플레이트는 src/app/api/webhook/route.ts에서 두 가지 webhook event를 처리하는 방법을 보여줍니다:

onSubscriptionActive - subscription이 활성화되면 트리거됨
onPaymentSucceeded - payment이 성공하면 트리거됨

이 handler 내부에 business logic을 추가하세요:

onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},

필요에 따라 webhook event를 더 추가하세요. 로컬 개발에서는 ngrok과 같은 도구를 사용하여 로컬 서버에 대한 secure tunnel을 만들고 webhook URL로 사용할 수 있습니다.

배포

Production 빌드

npm run build
npm start

Vercel에 배포

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) Vercel dashboard에 environment variables를 추가하는 것을 잊지 마세요!

Webhook URL 업데이트

배포한 후 Dodo Payments Dashboard에서 webhook URL을 업데이트하세요:

https://example.com/api/webhook

문제 해결

Module not found or build errors

node_modules를 삭제하고 dependencies를 다시 설치하세요:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

일반적인 원인:

잘못된 product ID - Dodo dashboard에 해당 product가 존재하는지 확인
.env의 API key 또는 environment 설정이 잘못됨
browser console과 terminal에서 오류 확인

Webhooks not receiving events

로컬 테스트에서는 ngrok을 사용하여 server를 외부에 노출하세요:

ngrok http 3000

Dodo dashboard의 webhook URL을 ngrok URL로 업데이트하세요. .env 파일의 webhook verification key도 올바른 값으로 업데이트해야 합니다.

Customer portal link doesn't work

src/app/components/Header.tsx에서 하드코딩된 CUSTOMER_ID를 사용자의 Dodo dashboard에서 가져온 실제 customer ID로 바꾸세요.또는 authentication system과 database를 통합하여 customer ID를 동적으로 가져오세요.

더 알아보기

지원

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

질문과 토론은 Discord community에 참여하세요
이슈와 업데이트는 GitHub repository에서 확인하세요
도움이 필요하면 support team에 문의하세요

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

개요

기능

사전 요구 사항

빠른 시작

프로젝트 구조

사용자 지정

Product Information 업데이트

Customer Data 사전 입력

Customer Portal 업데이트

Webhook Events

배포

Production 빌드

Vercel에 배포

Webhook URL 업데이트

문제 해결

더 알아보기

지원

​개요

​기능

​사전 요구 사항

​빠른 시작

​프로젝트 구조

​사용자 지정

​Product Information 업데이트

​Customer Data 사전 입력

​Customer Portal 업데이트

​Webhook Events

​배포

​Production 빌드

​Vercel에 배포

​Webhook URL 업데이트

​문제 해결

​더 알아보기

​지원

개요

기능

사전 요구 사항

빠른 시작

프로젝트 구조

사용자 지정

Product Information 업데이트

Customer Data 사전 입력

Customer Portal 업데이트

Webhook Events

배포

Production 빌드

Vercel에 배포

Webhook URL 업데이트

문제 해결

더 알아보기

지원