Next.js Minimal Boilerplate

Tổng quan

Boilerplate tối giản Next.js là một ứng dụng khởi đầu đã được kết nối sẵn với Dodo Payments. Thêm API keys và product IDs của bạn để có một trang định giá mở checkout, một webhook endpoint cho các sự kiện thanh toán và một liên kết đến Customer Portal.

Boilerplate này sử dụng Next.js 16 App Router với TypeScript, Tailwind CSS 4 và adaptor @dodopayments/nextjs. Để thêm các route handlers tương tự vào một ứng dụng hiện có, hãy xem Next.js Adaptor.

Tính năng

Boilerplate bao gồm:

Thiết lập nhanh: Từ lúc clone đến khi có một trang định giá đang chạy trong khoảng năm phút.
Checkout: Luồng checkout được cấu hình sẵn, xây dựng trên @dodopayments/nextjs.
Trang định giá: Trang định giá với giao diện tối, được tạo kiểu bằng Tailwind CSS.
Webhook Handler: Endpoint xác minh chữ ký của từng webhook và chạy code của bạn cho sự kiện đó.
Customer Portal: Liên kết trong header mở Customer Portal, nơi khách hàng quản lý các subscription của mình.
TypeScript: Định nghĩa product và handlers có kiểu.
Checkout điền sẵn: Truyền tên và email của khách hàng vào checkout để khách hàng không phải nhập lại.

Điều kiện tiên quyết

Trước khi bắt đầu, bạn cần:

Node.js 20.9 trở lên, phiên bản mà Next.js 16 yêu cầu.
Tài khoản Dodo Payments, để tạo API key và webhook signing secret trong dashboard.

Bắt đầu nhanh

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

Đăng ký tại Dodo Payments, sau đó lấy thông tin xác thực từ dashboard:

API Key: Tạo key trong Dashboard → Developer → API Keys.
Webhook Key: Thêm endpoint trong Dashboard → Developer → Webhooks, sau đó sao chép signing secret của endpoint. URL của endpoint phải là public và sử dụng HTTPS. Để nhận các sự kiện trên máy của bạn, hãy xem Webhook Events.

Tạo cả hai khi công tắc Live Mode trong sidebar đang tắt. Key ở test mode chỉ hoạt động với DODO_PAYMENTS_ENVIRONMENT=test_mode và các khoản thanh toán ở test mode không chuyển tiền thật.

Configure Environment Variables

Sao chép file mẫu để tạo file .env trong thư mục gốc:

cp .env.example .env

Đặt các giá trị thành thông tin xác thực Dodo Payments của bạn:

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

Các route handlers đọc những biến này:

DODO_PAYMENTS_API_KEY xác thực các checkout và Customer Portal handlers.
DODO_PAYMENTS_WEBHOOK_KEY xác minh webhook signatures.
DODO_PAYMENTS_RETURN_URL là nơi checkout gửi khách hàng đến sau khi thanh toán.
DODO_PAYMENTS_ENVIRONMENT là test_mode hoặc live_mode.

Không commit file .env vào version control. .gitignore của repository đã loại trừ file này.

Add Your Products

Thay thế các product mẫu trong src/lib/products.ts bằng product của bạn. Đặt mỗi product_id thành ID của một product trong Products ở dashboard:

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

Trang định giá hiển thị name, description, price và features từ file này. Checkout tính mức giá được đặt trên product trong Dodo Payments, vì vậy hãy giữ cho price đồng bộ với mức giá đó.

Run the Development Server

npm run dev

Mở http://localhost:3000 để xem trang định giá của bạn.

Cấu trúc dự án

Các checkout, Customer Portal và webhook route handlers nằm trong 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

Tùy chỉnh

Cập nhật thông tin product

Chỉnh sửa src/lib/products.ts để thay đổi:

Product IDs, lấy từ Products trong Dodo Payments dashboard
Prices
Features
Descriptions

Điền sẵn dữ liệu khách hàng

src/app/components/ProductCard.tsx gửi tên và email được hardcode trong mỗi checkout request. Thay thế chúng bằng thông tin của người dùng đã đăng nhập:

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

Cập nhật Customer Portal

Liên kết Customer Portal trong src/app/components/Header.tsx mở /api/customer-portal với customer ID được hardcode. Thay thế bằng Dodo Payments customer ID của người dùng đã đăng nhập:

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

Để lấy customer ID cho việc kiểm thử, hãy hoàn tất một giao dịch mua thử nghiệm, sau đó sao chép ID của khách hàng từ Customers trong dashboard. Trong production, lấy ID từ backend của bạn.

Webhook Events

Handler trong src/app/api/webhook/route.ts xác minh từng request bằng DODO_PAYMENTS_WEBHOOK_KEY, sau đó xử lý hai sự kiện:

onSubscriptionActive chạy khi một subscription trở nên active (subscription.active).
onPaymentSucceeded chạy khi một payment thành công (payment.succeeded).

Thêm business logic của bạn vào bên trong các handler này:

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

Để xử lý thêm các sự kiện, hãy thêm handlers tương ứng, chẳng hạn như onSubscriptionCancelled. Next.js Adaptor liệt kê mọi handler được hỗ trợ. Dodo Payments không thể truy cập localhost. Để phát triển cục bộ, hãy sử dụng một tunnel như ngrok để expose local server của bạn và dùng tunnel URL làm webhook endpoint.

Triển khai

Build cho production

npm run build
npm start

Triển khai lên Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) Thêm bốn environment variables trong Vercel dashboard và đặt DODO_PAYMENTS_RETURN_URL thành production URL của bạn.

Cập nhật Webhook URL

Sau khi triển khai, thêm production webhook URL trong Dodo Payments Dashboard, thay example.com bằng domain của bạn:

https://example.com/api/webhook

Mỗi endpoint có signing secret riêng. Sao chép secret của endpoint mới vào DODO_PAYMENTS_WEBHOOK_KEY trong production environment.

Khắc phục sự cố

Module not found or build errors

Xóa node_modules và package-lock.json, sau đó cài đặt lại dependencies:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Kiểm tra các nguyên nhân thường gặp sau:

Product ID không tồn tại trong Dodo Payments dashboard.
API key hoặc DODO_PAYMENTS_ENVIRONMENT trong .env không đúng. Key ở test mode chỉ hoạt động với test_mode.

Tìm lỗi trong browser console và terminal đang chạy npm run dev.

Webhooks not receiving events

Để kiểm thử cục bộ, hãy sử dụng ngrok để expose server của bạn:

ngrok http 3000

Trong Dodo dashboard của bạn, hãy thêm một endpoint với ngrok HTTPS URL theo sau là /api/webhook. Sao chép signing secret của endpoint đó vào DODO_PAYMENTS_WEBHOOK_KEY trong file .env.

Customer portal link doesn't work

Thay thế CUSTOMER_ID được hardcode trong src/app/components/Header.tsx bằng ID của một khách hàng trong Dodo Payments dashboard của bạn.Trong production, hãy lấy customer ID từ hệ thống xác thực và database của bạn.

Tìm hiểu thêm

Tài liệu Dodo Payments
Tài liệu Checkout Sessions
Tài liệu Webhooks
Next.js Adaptor: các tùy chọn cho các handlers Checkout, CustomerPortal và Webhooks

Hỗ trợ

Để được hỗ trợ về boilerplate:

Đặt câu hỏi trong cộng đồng Discord.
Báo cáo sự cố và theo dõi cập nhật trong GitHub repository.
Gửi email cho đội ngũ hỗ trợ.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Tổng quan

Tính năng

Điều kiện tiên quyết

Bắt đầu nhanh

Cấu trúc dự án

Tùy chỉnh

Cập nhật thông tin product

Điền sẵn dữ liệu khách hàng

Cập nhật Customer Portal

Webhook Events

Triển khai

Build cho production

Triển khai lên Vercel

Cập nhật Webhook URL

Khắc phục sự cố

Tìm hiểu thêm

Hỗ trợ

​Tổng quan

​Tính năng

​Điều kiện tiên quyết

​Bắt đầu nhanh

​Cấu trúc dự án

​Tùy chỉnh

​Cập nhật thông tin product

​Điền sẵn dữ liệu khách hàng

​Cập nhật Customer Portal

​Webhook Events

​Triển khai

​Build cho production

​Triển khai lên Vercel

​Cập nhật Webhook URL

​Khắc phục sự cố

​Tìm hiểu thêm

​Hỗ trợ

Tổng quan

Tính năng

Điều kiện tiên quyết

Bắt đầu nhanh

Cấu trúc dự án

Tùy chỉnh

Cập nhật thông tin product

Điền sẵn dữ liệu khách hàng

Cập nhật Customer Portal

Webhook Events

Triển khai

Build cho production

Triển khai lên Vercel

Cập nhật Webhook URL

Khắc phục sự cố

Tìm hiểu thêm

Hỗ trợ