Next.js Minimal Boilerplate

Aperçu

Le boilerplate minimal Next.js est une application de démarrage à laquelle Dodo Payments est déjà connecté. Ajoutez vos clés API et vos IDs de produits pour obtenir une page de tarification qui ouvre le checkout, un endpoint webhook pour les événements de paiement et un lien vers le Customer Portal.

Ce boilerplate utilise l’App Router de Next.js 16 avec TypeScript, Tailwind CSS 4 et l’adaptateur @dodopayments/nextjs. Pour ajouter les mêmes route handlers à une application existante, consultez Next.js Adaptor.

Caractéristiques

Le boilerplate inclut :

Configuration rapide : passez du clonage à une page de tarification fonctionnelle en environ cinq minutes.
Checkout : un flux de checkout préconfiguré basé sur @dodopayments/nextjs.
Page de tarification : une page de tarification au thème sombre, stylisée avec Tailwind CSS.
Gestionnaire de webhook : un endpoint qui vérifie chaque signature de webhook et exécute votre code pour l’événement.
Customer Portal : un lien dans l’en-tête qui ouvre le Customer Portal, où les clients gèrent leurs abonnements.
TypeScript : des définitions de produits et des handlers typés.
Checkout prérempli : transmet le nom et l’adresse e-mail du client au checkout afin qu’il n’ait pas à les saisir à nouveau.

Prérequis

Avant de commencer, vous avez besoin de :

Node.js 20.9 ou version ultérieure, requis par Next.js 16.
Un compte Dodo Payments, pour créer une clé API et un secret de signature de webhook dans le dashboard.

Démarrage rapide

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

Inscrivez-vous sur Dodo Payments, puis récupérez vos identifiants dans le dashboard :

Clé API : créez une clé dans Dashboard → Developer → API Keys.
Clé de webhook : ajoutez un endpoint dans Dashboard → Developer → Webhooks, puis copiez son secret de signature. L’URL de l’endpoint doit être publique et utiliser HTTPS. Pour recevoir des événements sur votre machine, consultez Webhook Events.

Créez les deux lorsque le bouton Live Mode dans la barre latérale est désactivé. Une clé en mode test fonctionne uniquement avec DODO_PAYMENTS_ENVIRONMENT=test_mode, et les paiements en mode test ne transfèrent pas d’argent réel.

Configure Environment Variables

Copiez le fichier d’exemple pour créer un fichier .env dans le répertoire racine :

cp .env.example .env

Définissez les valeurs avec vos identifiants Dodo Payments :

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

Les route handlers lisent ces variables :

DODO_PAYMENTS_API_KEY authentifie les handlers de checkout et de Customer Portal.
DODO_PAYMENTS_WEBHOOK_KEY vérifie les signatures de webhook.
DODO_PAYMENTS_RETURN_URL indique où le checkout redirige le client après le paiement.
DODO_PAYMENTS_ENVIRONMENT correspond à test_mode ou live_mode.

Ne commitez pas votre fichier .env dans le contrôle de version. Le fichier .gitignore du dépôt l’exclut déjà.

Add Your Products

Remplacez les produits d’exemple dans src/lib/products.ts par les vôtres. Définissez chaque product_id avec l’ID d’un produit présent dans Products de votre 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
];

La page de tarification affiche name, description, price et features depuis ce fichier. Le checkout facture le prix défini sur le produit dans Dodo Payments ; veillez donc à synchroniser price avec celui-ci.

Run the Development Server

npm run dev

Ouvrez http://localhost:3000 pour afficher votre page de tarification.

Structure du projet

Les route handlers du checkout, du Customer Portal et des webhooks se trouvent sous 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

Personnalisation

Mettre à jour les informations produit

Modifiez src/lib/products.ts pour changer :

Les IDs de produits, depuis Products dans votre dashboard Dodo Payments
Les prix
Les fonctionnalités
Les descriptions

Préremplir les données client

src/app/components/ProductCard.tsx envoie un nom et une adresse e-mail codés en dur avec chaque requête de checkout. Remplacez-les par les informations de l’utilisateur connecté :

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

Mettre à jour le Customer Portal

Le lien Customer Portal dans src/app/components/Header.tsx ouvre /api/customer-portal avec un ID client codé en dur. Remplacez-le par l’ID client Dodo Payments de l’utilisateur connecté :

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

Pour obtenir un ID client à des fins de test, effectuez un achat test, puis copiez l’ID du client depuis Customers dans le dashboard. En production, récupérez l’ID depuis votre backend.

Événements webhook

Le handler dans src/app/api/webhook/route.ts vérifie chaque requête avec DODO_PAYMENTS_WEBHOOK_KEY, puis gère deux événements :

onSubscriptionActive s’exécute lorsqu’un abonnement devient actif (subscription.active).
onPaymentSucceeded s’exécute lorsqu’un paiement réussit (payment.succeeded).

Ajoutez votre logique métier dans ces handlers :

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

Pour gérer davantage d’événements, ajoutez leurs handlers, comme onSubscriptionCancelled. Next.js Adaptor répertorie tous les handlers pris en charge. Dodo Payments ne peut pas atteindre localhost. Pour le développement local, utilisez un tunnel tel que ngrok afin d’exposer votre serveur local, et utilisez l’URL du tunnel comme endpoint webhook.

Déploiement

Générer pour la production

npm run build
npm start

Déployer sur Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) Ajoutez les quatre variables d’environnement dans le dashboard Vercel et définissez DODO_PAYMENTS_RETURN_URL avec votre URL de production.

Mettre à jour l’URL du webhook

Après le déploiement, ajoutez l’URL de votre webhook de production dans le Dodo Payments Dashboard, en remplaçant example.com par votre domaine :

https://example.com/api/webhook

Chaque endpoint possède son propre secret de signature. Copiez le secret du nouvel endpoint dans DODO_PAYMENTS_WEBHOOK_KEY dans votre environnement de production.

Résolution des problèmes

Module not found or build errors

Supprimez node_modules et package-lock.json, puis réinstallez les dépendances :

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Vérifiez les causes courantes suivantes :

L’ID du produit n’existe pas dans votre dashboard Dodo Payments.
La clé API ou DODO_PAYMENTS_ENVIRONMENT dans .env est incorrecte. Une clé en mode test fonctionne uniquement avec test_mode.

Recherchez l’erreur dans la console du navigateur et dans le terminal qui exécute npm run dev.

Webhooks not receiving events

Pour les tests locaux, utilisez ngrok afin d’exposer votre serveur :

ngrok http 3000

Dans votre Dodo dashboard, ajoutez un endpoint avec l’URL HTTPS ngrok suivie de /api/webhook. Copiez le secret de signature de cet endpoint dans DODO_PAYMENTS_WEBHOOK_KEY de votre fichier .env.

Customer portal link doesn't work

Remplacez CUSTOMER_ID codé en dur dans src/app/components/Header.tsx par l’ID d’un client présent dans votre dashboard Dodo Payments.En production, récupérez plutôt l’ID client depuis votre système d’authentification et votre base de données.

En savoir plus

Documentation Dodo Payments
Documentation des Checkout Sessions
Documentation des webhooks
Next.js Adaptor : options pour les handlers Checkout, CustomerPortal et Webhooks

Assistance

Pour obtenir de l’aide avec le boilerplate :

Posez vos questions dans la communauté Discord.
Signalez les problèmes et suivez les mises à jour dans le dépôt GitHub.
Envoyez un e-mail à l’équipe d’assistance.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Aperçu

Caractéristiques

Prérequis

Démarrage rapide

Structure du projet

Personnalisation

Mettre à jour les informations produit

Préremplir les données client

Mettre à jour le Customer Portal

Événements webhook

Déploiement

Générer pour la production

Déployer sur Vercel

Mettre à jour l’URL du webhook

Résolution des problèmes

En savoir plus

Assistance

​Aperçu

​Caractéristiques

​Prérequis

​Démarrage rapide

​Structure du projet

​Personnalisation

​Mettre à jour les informations produit

​Préremplir les données client

​Mettre à jour le Customer Portal

​Événements webhook

​Déploiement

​Générer pour la production

​Déployer sur Vercel

​Mettre à jour l’URL du webhook

​Résolution des problèmes

​En savoir plus

​Assistance

Aperçu

Caractéristiques

Prérequis

Démarrage rapide

Structure du projet

Personnalisation

Mettre à jour les informations produit

Préremplir les données client

Mettre à jour le Customer Portal

Événements webhook

Déploiement

Générer pour la production

Déployer sur Vercel

Mettre à jour l’URL du webhook

Résolution des problèmes

En savoir plus

Assistance