Next.js Minimal Boilerplate

개요

Next.js minimal boilerplate는 Dodo Payments가 이미 연결된 starter app입니다. API keys와 product IDs를 추가하면 checkout을 여는 pricing page, payment events를 위한 webhook endpoint, Customer Portal 링크를 사용할 수 있습니다.

이 boilerplate는 TypeScript, Tailwind CSS 4, 그리고 @dodopayments/nextjs adaptor를 사용하는 Next.js 16 App Router를 기반으로 합니다. 기존 app에 동일한 route handlers를 추가하려면 Next.js Adaptor를 참조하세요.

기능

이 boilerplate에는 다음이 포함됩니다:

간편한 설정: clone부터 작동하는 pricing page까지 약 5분이면 완료할 수 있습니다.
Checkout: @dodopayments/nextjs를 기반으로 사전 구성된 checkout flow입니다.
Pricing Page: Tailwind CSS로 스타일링된 dark-themed pricing page입니다.
Webhook Handler: 각 webhook signature를 검증하고 event에 대한 코드를 실행하는 endpoint입니다.
Customer Portal: 고객이 subscription을 관리할 수 있는 Customer Portal을 여는 header link입니다.
TypeScript: 타입이 지정된 product definitions와 handlers입니다.
사전 입력된 Checkout: 고객의 이름과 email을 checkout에 전달하므로 고객이 다시 입력할 필요가 없습니다.

사전 요구 사항

시작하기 전에 다음이 필요합니다:

Next.js 16에 필요한 Node.js 20.9 이상
dashboard에서 API key와 webhook signing secret을 생성할 수 있는 Dodo Payments account

빠른 시작

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에서 key를 생성합니다.
Webhook Key: Dashboard → Developer → Webhooks에서 endpoint를 추가한 다음 signing secret을 복사합니다. endpoint URL은 public이어야 하며 HTTPS를 사용해야 합니다. 컴퓨터에서 event를 수신하려면 Webhook Events를 참조하세요.

사이드바의 Live Mode switch가 꺼진 상태에서 두 key를 모두 생성하세요. test mode key는 DODO_PAYMENTS_ENVIRONMENT=test_mode에서만 작동하며 test mode payment는 실제 자금을 이동시키지 않습니다.

Configure Environment Variables

example file을 복사하여 root directory에 .env file을 생성합니다:

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

route handlers는 다음 variables를 읽습니다:

DODO_PAYMENTS_API_KEY는 checkout 및 Customer Portal handlers를 인증합니다.
DODO_PAYMENTS_WEBHOOK_KEY는 webhook signatures를 검증합니다.
DODO_PAYMENTS_RETURN_URL는 payment 후 checkout이 customer를 보내는 위치입니다.
DODO_PAYMENTS_ENVIRONMENT는 test_mode 또는 live_mode입니다.

.env file을 version control에 commit하지 마세요. repository의 .gitignore가 이미 해당 file을 제외합니다.

Add Your Products

src/lib/products.ts의 sample products를 원하는 products로 교체합니다. 각 product_id를 dashboard의 Products 아래에 있는 product의 ID로 설정하세요:

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

pricing page는 이 file에서 name, description, price, features를 표시합니다. Checkout은 Dodo Payments의 product에 설정된 price를 청구하므로 price가 product와 동기화되어 있는지 확인하세요.

Run the Development Server

npm run dev

http://localhost:3000을 열어 pricing page를 확인합니다.

Project Structure

checkout, Customer Portal, webhook route handlers는 src/app/api/ 아래에 있습니다:

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를 편집하여 다음을 변경합니다:

Dodo Payments dashboard의 Products에 있는 Product IDs
Prices
Features
Descriptions

Customer Data 사전 입력

src/app/components/ProductCard.tsx는 각 checkout request와 함께 hardcoded name과 email을 전송합니다. 이를 로그인한 사용자의 정보로 교체하세요:

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

Customer Portal 업데이트

src/app/components/Header.tsx의 Customer Portal link는 hardcoded customer ID를 사용하여 /api/customer-portal를 엽니다. 이를 로그인한 사용자의 Dodo Payments customer ID로 교체하세요:

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

테스트를 위한 customer ID를 가져오려면 test purchase를 완료한 다음 dashboard의 Customers에서 customer의 ID를 복사합니다. production에서는 backend에서 ID를 가져오세요.

Webhook Events

src/app/api/webhook/route.ts의 handler는 DODO_PAYMENTS_WEBHOOK_KEY를 사용하여 각 request를 검증한 다음 두 event를 처리합니다:

subscription이 active 상태가 되면 onSubscriptionActive가 실행됩니다 (subscription.active).
payment이 성공하면 onPaymentSucceeded가 실행됩니다 (payment.succeeded).

이 handlers 안에 business logic을 추가하세요:

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

더 많은 event를 처리하려면 onSubscriptionCancelled와 같은 handlers를 추가하세요. Next.js Adaptor에서 지원되는 모든 handlers를 확인할 수 있습니다. Dodo Payments는 localhost에 접근할 수 없습니다. local development에서는 ngrok과 같은 tunnel을 사용하여 local server를 노출하고 tunnel URL을 webhook endpoint로 사용하세요.

Deployment

Production용 Build

npm run build
npm start

Vercel에 Deploy

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) Vercel dashboard에서 네 개의 environment variables를 추가하고 DODO_PAYMENTS_RETURN_URL를 production URL로 설정하세요.

Webhook URL 업데이트

배포한 후 Dodo Payments Dashboard에 production webhook URL을 추가하고, example.com 대신 domain을 입력하세요:

https://example.com/api/webhook

각 endpoint에는 고유한 signing secret이 있습니다. 새 endpoint의 secret을 production environment의 DODO_PAYMENTS_WEBHOOK_KEY에 복사하세요.

문제 해결

Module not found or build errors

node_modules와 package-lock.json를 삭제한 다음 dependencies를 다시 설치합니다:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

다음과 같은 일반적인 원인을 확인하세요:

Dodo Payments dashboard에 product ID가 존재하지 않습니다.
.env의 API key 또는 DODO_PAYMENTS_ENVIRONMENT가 잘못되었습니다. test mode key는 test_mode에서만 작동합니다.

브라우저 console과 npm run dev를 실행하는 terminal에서 error를 확인하세요.

Webhooks not receiving events

local testing에서는 ngrok을 사용하여 server를 노출하세요:

ngrok http 3000

Dodo dashboard에서 ngrok HTTPS URL 뒤에 /api/webhook를 붙인 endpoint를 추가합니다. 해당 endpoint의 signing secret을 .env file의 DODO_PAYMENTS_WEBHOOK_KEY에 복사하세요.

Customer portal link doesn't work

src/app/components/Header.tsx의 hardcoded CUSTOMER_ID를 Dodo Payments dashboard에 있는 customer의 ID로 교체하세요.production에서는 대신 authentication system과 database에서 customer ID를 가져오세요.

더 알아보기

Dodo Payments Documentation
Checkout Sessions Documentation
Webhooks Documentation
Next.js Adaptor: Checkout, CustomerPortal, Webhooks handlers의 options

지원

boilerplate에 대한 도움이 필요하면 다음을 이용하세요:

Discord community에서 질문하세요.
GitHub repository에서 issue를 신고하고 업데이트를 확인하세요.
support team에 email을 보내세요.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

개요

기능

사전 요구 사항

빠른 시작

Project Structure

사용자 지정

Product Information 업데이트

Customer Data 사전 입력

Customer Portal 업데이트

Webhook Events

Deployment

Production용 Build

Vercel에 Deploy

Webhook URL 업데이트

문제 해결

더 알아보기

지원