Next.js Minimal Boilerplate

Get started quickly with our minimal Next.js boilerplate for integrating Dodo Payments into your Next.js application

Overview

The Next.js minimal boilerplate provides a ready-to-use starting point for integrating Dodo Payments with your Next.js application. This template includes checkout sessions, webhook handling, customer portal, and modern UI components to help you start accepting payments quickly.

This boilerplate uses Next.js 16 App Router with TypeScript, Tailwind CSS 4, and the @dodopayments/nextjs adapter.

Features

• Quick Setup - Get started in under 5 minutes
• Payment Integration - Pre-configured checkout flow using @dodopayments/nextjs
• Modern UI - Clean, dark-themed pricing page with Tailwind CSS
• Webhook Handler - Ready-to-use webhook endpoint for payment events
• Customer Portal - One-click subscription management
• TypeScript - Fully typed with minimal, focused types
• Pre-filled Checkout - Demonstrates passing customer data to improve UX

Prerequisites

Before you begin, make sure you have:

• Node.js 20.9+ (required for Next.js 16)
• Dodo Payments account (to access API and Webhook Keys from dashboard)

Quick Start

1. Clone the Repository

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

2. Install Dependencies

   npm install
   

3. Get API Credentials

   Sign up at Dodo Payments and get your credentials from the dashboard:

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

   Make sure you’re in Test Mode while developing!

4. Configure Environment Variables

   Create a .env file in the root directory:

   cp .env.example .env
   

   Update the values with your 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
   

   Never commit your .env file to version control. It’s already included in .gitignore.

5. Add Your Products

   Update src/lib/products.ts with your actual product IDs from Dodo Payments:

   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. Run the Development Server

   npm run dev
   

   Open http://localhost:3000 to see your pricing page!

Project Structure

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

Customization

Update Product Information

Edit src/lib/products.ts to modify:

• Product IDs (from your Dodo dashboard)
• Pricing
• Features
• Descriptions

Pre-fill Customer Data

In src/app/components/ProductCard.tsx, replace the hardcoded values with your actual user data:

customer: {
  name: "John Doe",
  email: "[e-mail]",
},

Update Customer Portal

In src/app/components/Header.tsx, replace the hardcoded customer ID:

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

You can complete a test purchase to get the customer ID for testing.

Webhook Events

The boilerplate demonstrates handling two webhook events in src/app/api/webhook/route.ts:

• onSubscriptionActive - Triggered when a subscription becomes active
• onPaymentSucceeded - Triggered when a payment is successful

Add your business logic inside these handlers:

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

Add more webhook events as needed.

For local development, you can use tools like ngrok to create a secure tunnel to your local server and use it as your webhook URL.

Deployment

Build for Production

npm run build
npm start

Deploy to Vercel

Don’t forget to add your environment variables in the Vercel dashboard!

Update Webhook URL

After deploying, update your webhook URL in the Dodo Payments Dashboard:

https://example.com/api/webhook

Troubleshooting

Module not found or build errors

Delete node_modules and reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Common causes:

• Invalid product ID - verify it exists in your Dodo dashboard
• Wrong API key or environment setting in .env
• Check browser console and terminal for errors

Webhooks not receiving events

For local testing, use ngrok to expose your server:

ngrok http 3000

Update the webhook URL in your Dodo dashboard to the ngrok URL. Remember to update your .env file with the correct webhook verification key.

Customer portal link doesn't work

Replace the hardcoded CUSTOMER_ID in src/app/components/Header.tsx with an actual customer ID from your Dodo dashboard.

Or integrate your authentication system and database to fetch the customer ID dynamically.

Learn More

• Dodo Payments Documentation
• Checkout Sessions Documentation
• Webhooks Documentation

Support

Need help with the boilerplate?

• Join our Discord community for questions and discussions
• Check the GitHub repository for issues and updates
• Contact our support team for assistance