Next.js Minimal Boilerplate

Ikhtisar

Boilerplate minimal Next.js adalah aplikasi awal dengan Dodo Payments yang sudah terhubung. Tambahkan API keys dan product IDs Anda, lalu Anda mendapatkan halaman harga yang membuka checkout, endpoint webhook untuk payment events, dan tautan ke Customer Portal.

Boilerplate ini menggunakan Next.js 16 App Router dengan TypeScript, Tailwind CSS 4, dan adaptor @dodopayments/nextjs. Untuk menambahkan route handlers yang sama ke aplikasi yang sudah ada, lihat Next.js Adaptor.

Fitur

Boilerplate ini mencakup:

Penyiapan Cepat: Beralih dari clone ke halaman harga yang berjalan dalam sekitar lima menit.
Checkout: Alur checkout yang telah dikonfigurasi sebelumnya, dibangun di atas @dodopayments/nextjs.
Halaman Harga: Halaman harga bertema gelap yang ditata dengan Tailwind CSS.
Webhook Handler: Endpoint yang memverifikasi setiap webhook signature dan menjalankan kode Anda untuk event tersebut.
Customer Portal: Tautan header yang membuka Customer Portal, tempat pelanggan mengelola subscription mereka.
TypeScript: Definisi product dan handler yang memiliki type.
Checkout Terisi Otomatis: Meneruskan nama dan email pelanggan ke checkout, sehingga pelanggan tidak perlu mengetikkannya lagi.

Prasyarat

Sebelum memulai, Anda memerlukan:

Node.js 20.9 atau yang lebih baru, yang diperlukan oleh Next.js 16.
Akun Dodo Payments, untuk membuat API key dan webhook signing secret di dashboard.

Mulai Cepat

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

Daftar di Dodo Payments, lalu dapatkan kredensial Anda dari dashboard:

API Key: Buat key di Dashboard → Developer → API Keys.
Webhook Key: Tambahkan endpoint di Dashboard → Developer → Webhooks, lalu salin signing secret-nya. URL endpoint harus bersifat publik dan menggunakan HTTPS. Untuk menerima event di mesin Anda, lihat Webhook Events.

Buat keduanya saat tombol Live Mode di sidebar dalam keadaan nonaktif. Key test mode hanya berfungsi dengan DODO_PAYMENTS_ENVIRONMENT=test_mode, dan payment dalam test mode tidak memindahkan uang sungguhan.

Configure Environment Variables

Salin file contoh untuk membuat file .env di direktori root:

cp .env.example .env

Atur nilainya ke kredensial Dodo Payments Anda:

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 membaca variabel berikut:

DODO_PAYMENTS_API_KEY mengautentikasi checkout dan Customer Portal handlers.
DODO_PAYMENTS_WEBHOOK_KEY memverifikasi webhook signatures.
DODO_PAYMENTS_RETURN_URL adalah tempat checkout mengarahkan pelanggan setelah payment.
DODO_PAYMENTS_ENVIRONMENT adalah test_mode atau live_mode.

Jangan commit file .env Anda ke version control. .gitignore milik repository sudah mengecualikannya.

Add Your Products

Ganti sample products di src/lib/products.ts dengan milik Anda sendiri. Atur setiap product_id ke ID product di bawah Products pada dashboard Anda:

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

Halaman harga menampilkan name, description, price, dan features dari file ini. Checkout membebankan harga yang ditetapkan pada product di Dodo Payments, jadi pastikan price tetap sinkron dengannya.

Run the Development Server

npm run dev

Buka http://localhost:3000 untuk melihat halaman harga Anda.

Struktur Project

Checkout, Customer Portal, dan webhook route handlers berada di bawah 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

Kustomisasi

Perbarui Informasi Product

Edit src/lib/products.ts untuk mengubah:

Product IDs, dari Products di dashboard Dodo Payments Anda
Harga
Fitur
Deskripsi

Isi Otomatis Data Pelanggan

src/app/components/ProductCard.tsx mengirimkan nama dan email hardcoded dalam setiap checkout request. Ganti dengan detail pengguna yang sedang login:

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

Perbarui Customer Portal

Tautan Customer Portal di src/app/components/Header.tsx membuka /api/customer-portal dengan customer ID hardcoded. Ganti dengan Dodo Payments customer ID milik pengguna yang sedang login:

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

Untuk mendapatkan customer ID untuk pengujian, selesaikan test purchase, lalu salin customer ID dari Customers di dashboard. Dalam production, ambil ID dari backend Anda.

Webhook Events

Handler di src/app/api/webhook/route.ts memverifikasi setiap request dengan DODO_PAYMENTS_WEBHOOK_KEY, lalu menangani dua event:

onSubscriptionActive berjalan saat subscription menjadi active (subscription.active).
onPaymentSucceeded berjalan saat payment berhasil (payment.succeeded).

Tambahkan business logic Anda di dalam handler ini:

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

Untuk menangani lebih banyak event, tambahkan handler-nya, seperti onSubscriptionCancelled. Next.js Adaptor mencantumkan semua handler yang didukung. Dodo Payments tidak dapat menjangkau localhost. Untuk local development, gunakan tunnel seperti ngrok untuk mengekspos server lokal Anda, dan gunakan URL tunnel tersebut sebagai webhook endpoint.

Deployment

Build untuk Production

npm run build
npm start

Deploy ke Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) Tambahkan keempat environment variables di dashboard Vercel, lalu atur DODO_PAYMENTS_RETURN_URL ke URL production Anda.

Perbarui Webhook URL

Setelah melakukan deployment, tambahkan production webhook URL Anda di Dodo Payments Dashboard, dengan domain Anda menggantikan example.com:

https://example.com/api/webhook

Setiap endpoint memiliki signing secret sendiri. Salin secret endpoint baru ke DODO_PAYMENTS_WEBHOOK_KEY di environment production Anda.

Pemecahan Masalah

Module not found or build errors

Hapus node_modules dan package-lock.json, lalu instal ulang dependencies:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Periksa penyebab umum berikut:

Product ID tidak ada di dashboard Dodo Payments Anda.
API key atau DODO_PAYMENTS_ENVIRONMENT di .env salah. Key test mode hanya berfungsi dengan test_mode.

Cari error di browser console dan terminal yang menjalankan npm run dev.

Webhooks not receiving events

Untuk pengujian lokal, gunakan ngrok untuk mengekspos server Anda:

ngrok http 3000

Di Dodo dashboard Anda, tambahkan endpoint dengan URL HTTPS ngrok diikuti /api/webhook. Salin signing secret endpoint tersebut ke DODO_PAYMENTS_WEBHOOK_KEY di file .env Anda.

Customer portal link doesn't work

Ganti CUSTOMER_ID yang hardcoded di src/app/components/Header.tsx dengan ID customer di dashboard Dodo Payments Anda.Dalam production, dapatkan customer ID dari authentication system dan database Anda.

Pelajari Lebih Lanjut

Dokumentasi Dodo Payments
Dokumentasi Checkout Sessions
Dokumentasi Webhooks
Next.js Adaptor: opsi untuk handler Checkout, CustomerPortal, dan Webhooks

Dukungan

Untuk mendapatkan bantuan terkait boilerplate:

Ajukan pertanyaan di komunitas Discord.
Laporkan masalah dan ikuti pembaruan di repository GitHub.
Kirim email ke tim dukungan.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Ikhtisar

Fitur

Prasyarat

Mulai Cepat

Struktur Project

Kustomisasi

Perbarui Informasi Product

Isi Otomatis Data Pelanggan

Perbarui Customer Portal

Webhook Events

Deployment

Build untuk Production

Deploy ke Vercel

Perbarui Webhook URL

Pemecahan Masalah

Pelajari Lebih Lanjut

Dukungan

​Ikhtisar

​Fitur

​Prasyarat

​Mulai Cepat

​Struktur Project

​Kustomisasi

​Perbarui Informasi Product

​Isi Otomatis Data Pelanggan

​Perbarui Customer Portal

​Webhook Events

​Deployment

​Build untuk Production

​Deploy ke Vercel

​Perbarui Webhook URL

​Pemecahan Masalah

​Pelajari Lebih Lanjut

​Dukungan

Ikhtisar

Fitur

Prasyarat

Mulai Cepat

Struktur Project

Kustomisasi

Perbarui Informasi Product

Isi Otomatis Data Pelanggan

Perbarui Customer Portal

Webhook Events

Deployment

Build untuk Production

Deploy ke Vercel

Perbarui Webhook URL

Pemecahan Masalah

Pelajari Lebih Lanjut

Dukungan