Next.js Minimal Boilerplate

Übersicht

Das minimale Next.js-Boilerplate ist eine Starter-App, in der Dodo Payments bereits verbunden ist. Fügen Sie Ihre API-Schlüssel und Produkt-IDs hinzu, und Sie erhalten eine Preisseite, die den Checkout öffnet, einen Webhook-Endpunkt für Zahlungsereignisse und einen Link zum Customer Portal.

Dieses Boilerplate verwendet den Next.js 16 App Router mit TypeScript, Tailwind CSS 4 und dem @dodopayments/nextjs-Adaptor. Informationen zum Hinzufügen derselben Route-Handler zu einer bestehenden App finden Sie unter Next.js Adaptor.

Funktionen

Das Boilerplate umfasst:

Schnelle Einrichtung: Vom Klonen bis zu einer laufenden Preisseite in etwa fünf Minuten.
Checkout: Ein vorkonfigurierter Checkout-Ablauf auf Basis von @dodopayments/nextjs.
Preisseite: Eine dunkel gestaltete Preisseite mit Tailwind CSS.
Webhook-Handler: Ein Endpunkt, der jede Webhook-Signatur überprüft und Ihren Code für das Ereignis ausführt.
Customer Portal: Ein Link in der Kopfzeile, der das Customer Portal öffnet, in dem Kunden ihre Abonnements verwalten.
TypeScript: Typisierte Produktdefinitionen und Handler.
Vorausgefüllter Checkout: Übermittelt den Namen und die E-Mail-Adresse des Kunden an den Checkout, damit der Kunde diese nicht erneut eingeben muss.

Voraussetzungen

Bevor Sie beginnen, benötigen Sie:

Node.js 20.9 oder höher, wie von Next.js 16 vorausgesetzt.
Ein Dodo Payments-Konto, um im Dashboard einen API-Schlüssel und ein Webhook-Signaturgeheimnis zu erstellen.

Schnellstart

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

Registrieren Sie sich bei Dodo Payments und rufen Sie anschließend Ihre Zugangsdaten im Dashboard ab:

API Key: Erstellen Sie einen Schlüssel unter Dashboard → Developer → API Keys.
Webhook Key: Fügen Sie unter Dashboard → Developer → Webhooks einen Endpunkt hinzu und kopieren Sie anschließend dessen Signaturgeheimnis. Die Endpunkt-URL muss öffentlich zugänglich sein und HTTPS verwenden. Informationen zum Empfangen von Ereignissen auf Ihrem Computer finden Sie unter Webhook Events.

Erstellen Sie beide, während der Schalter Live Mode in der Seitenleiste deaktiviert ist. Ein Testmodus-Schlüssel funktioniert nur mit DODO_PAYMENTS_ENVIRONMENT=test_mode, und Zahlungen im Testmodus bewegen kein echtes Geld.

Configure Environment Variables

Kopieren Sie die Beispieldatei, um im Stammverzeichnis eine .env-Datei zu erstellen:

cp .env.example .env

Legen Sie die Werte für Ihre Dodo Payments-Zugangsdaten fest:

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

Die Route-Handler lesen diese Variablen aus:

DODO_PAYMENTS_API_KEY authentifiziert die Checkout- und Customer-Portal-Handler.
DODO_PAYMENTS_WEBHOOK_KEY überprüft Webhook-Signaturen.
DODO_PAYMENTS_RETURN_URL ist das Ziel, an das der Checkout den Kunden nach der Zahlung weiterleitet.
DODO_PAYMENTS_ENVIRONMENT ist test_mode oder live_mode.

Committen Sie Ihre .env-Datei nicht in die Versionsverwaltung. Die .gitignore des Repositorys schließt sie bereits aus.

Add Your Products

Ersetzen Sie die Beispielprodukte in src/lib/products.ts durch Ihre eigenen. Legen Sie für jedes product_id die ID eines Produkts unter Products in Ihrem Dashboard fest:

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

Die Preisseite zeigt name, description, price und features aus dieser Datei an. Der Checkout berechnet den für das Produkt in Dodo Payments festgelegten Preis. Halten Sie daher price mit diesem Preis synchron.

Run the Development Server

npm run dev

Öffnen Sie http://localhost:3000, um Ihre Preisseite anzuzeigen.

Projektstruktur

Die Route-Handler für Checkout, Customer Portal und Webhooks befinden sich unter 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

Anpassung

Produktinformationen aktualisieren

Bearbeiten Sie src/lib/products.ts, um Folgendes zu ändern:

Produkt-IDs aus Products in Ihrem Dodo Payments-Dashboard
Preise
Funktionen
Beschreibungen

Kundendaten vorausfüllen

src/app/components/ProductCard.tsx sendet mit jeder Checkout-Anfrage einen fest codierten Namen und eine fest codierte E-Mail-Adresse. Ersetzen Sie diese durch die Daten des angemeldeten Benutzers:

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

Customer Portal aktualisieren

Der Link Customer Portal in src/app/components/Header.tsx öffnet /api/customer-portal mit einer fest codierten Kunden-ID. Ersetzen Sie sie durch die Dodo Payments-Kunden-ID des angemeldeten Benutzers:

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

Um eine Kunden-ID zum Testen zu erhalten, führen Sie einen Testkauf durch und kopieren Sie anschließend die Kunden-ID unter Customers im Dashboard. Rufen Sie die ID in der Produktion von Ihrem Backend ab.

Webhook-Ereignisse

Der Handler in src/app/api/webhook/route.ts überprüft jede Anfrage mit DODO_PAYMENTS_WEBHOOK_KEY und verarbeitet anschließend zwei Ereignisse:

onSubscriptionActive wird ausgeführt, wenn ein Abonnement aktiv wird (subscription.active).
onPaymentSucceeded wird ausgeführt, wenn eine Zahlung erfolgreich ist (payment.succeeded).

Fügen Sie Ihre Geschäftslogik in diese Handler ein:

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

Um weitere Ereignisse zu verarbeiten, fügen Sie deren Handler hinzu, z. B. onSubscriptionCancelled. Der Next.js Adaptor listet alle unterstützten Handler auf. Dodo Payments kann localhost nicht erreichen. Verwenden Sie für die lokale Entwicklung einen Tunnel wie ngrok, um Ihren lokalen Server öffentlich zugänglich zu machen, und verwenden Sie die Tunnel-URL als Webhook-Endpunkt.

Bereitstellung

Für die Produktion erstellen

npm run build
npm start

In Vercel bereitstellen

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) Fügen Sie die vier Umgebungsvariablen im Vercel-Dashboard hinzu und setzen Sie DODO_PAYMENTS_RETURN_URL auf Ihre Produktions-URL.

Webhook-URL aktualisieren

Fügen Sie nach der Bereitstellung Ihre Webhook-URL für die Produktion im Dodo Payments Dashboard hinzu, wobei Ihre Domain anstelle von example.com steht:

https://example.com/api/webhook

Jeder Endpunkt besitzt ein eigenes Signaturgeheimnis. Kopieren Sie das Geheimnis des neuen Endpunkts in DODO_PAYMENTS_WEBHOOK_KEY in Ihrer Produktionsumgebung.

Fehlerbehebung

Module not found or build errors

Löschen Sie node_modules und package-lock.json und installieren Sie anschließend die Abhängigkeiten neu:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Prüfen Sie diese häufigen Ursachen:

Die Produkt-ID ist in Ihrem Dodo Payments-Dashboard nicht vorhanden.
Der API-Schlüssel oder DODO_PAYMENTS_ENVIRONMENT in .env ist falsch. Ein Testmodus-Schlüssel funktioniert nur mit test_mode.

Suchen Sie im Browser-Konsolenfenster und im Terminal, in dem npm run dev ausgeführt wird, nach dem Fehler.

Webhooks not receiving events

Verwenden Sie für lokale Tests ngrok, um Ihren Server öffentlich zugänglich zu machen:

ngrok http 3000

Fügen Sie in Ihrem Dodo-Dashboard einen Endpunkt mit der HTTPS-URL von ngrok gefolgt von /api/webhook hinzu. Kopieren Sie das Signaturgeheimnis dieses Endpunkts in DODO_PAYMENTS_WEBHOOK_KEY in Ihrer .env-Datei.

Customer portal link doesn't work

Ersetzen Sie das fest codierte CUSTOMER_ID in src/app/components/Header.tsx durch die ID eines Kunden in Ihrem Dodo Payments-Dashboard.Rufen Sie die Kunden-ID in der Produktion stattdessen von Ihrem Authentifizierungssystem und Ihrer Datenbank ab.

Weitere Informationen

Dodo Payments-Dokumentation
Dokumentation zu Checkout Sessions
Dokumentation zu Webhooks
Next.js Adaptor: Optionen für die Checkout-, CustomerPortal- und Webhooks-Handler

Support

Hilfe zum Boilerplate:

Stellen Sie Fragen in der Discord-Community.
Melden Sie Probleme und verfolgen Sie Aktualisierungen im GitHub-Repository.
Schreiben Sie dem Support-Team.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Übersicht

Funktionen

Voraussetzungen

Schnellstart

Projektstruktur

Anpassung

Produktinformationen aktualisieren

Kundendaten vorausfüllen

Customer Portal aktualisieren

Webhook-Ereignisse

Bereitstellung

Für die Produktion erstellen

In Vercel bereitstellen

Webhook-URL aktualisieren

Fehlerbehebung

Weitere Informationen

Support

​Übersicht

​Funktionen

​Voraussetzungen

​Schnellstart

​Projektstruktur

​Anpassung

​Produktinformationen aktualisieren

​Kundendaten vorausfüllen

​Customer Portal aktualisieren

​Webhook-Ereignisse

​Bereitstellung

​Für die Produktion erstellen

​In Vercel bereitstellen

​Webhook-URL aktualisieren

​Fehlerbehebung

​Weitere Informationen

​Support

Übersicht

Funktionen

Voraussetzungen

Schnellstart

Projektstruktur

Anpassung

Produktinformationen aktualisieren

Kundendaten vorausfüllen

Customer Portal aktualisieren

Webhook-Ereignisse

Bereitstellung

Für die Produktion erstellen

In Vercel bereitstellen

Webhook-URL aktualisieren

Fehlerbehebung

Weitere Informationen

Support