Vai al contenuto principale

​
Panoramica

Il boilerplate minimale di Next.js fornisce un punto di partenza pronto all’uso per integrare Dodo Payments con la tua applicazione Next.js. Questo template include sessioni di checkout, gestione dei webhook, portale clienti e componenti UI moderni per aiutarti ad iniziare ad accettare pagamenti rapidamente.
Questo boilerplate utilizza Next.js 16 App Router con TypeScript, Tailwind CSS 4 e l’adapter @dodopayments/nextjs.

​
Caratteristiche

  • Quick Setup - Avvio in meno di 5 minuti
  • Payment Integration - Flusso di checkout preconfigurato che utilizza @dodopayments/nextjs
  • Modern UI - Pagina dei prezzi pulita a tema scuro con Tailwind CSS
  • Webhook Handler - Endpoint webhook pronto all’uso per gli eventi di pagamento
  • Customer Portal - Gestione degli abbonamenti con un solo clic
  • TypeScript - Tipizzazione completa con tipi minimi e mirati
  • Pre-filled Checkout - Dimostra come passare i dati del cliente per migliorare l’esperienza utente

​
Requisiti

Prima di iniziare, assicurati di avere:
  • Node.js 20.9+ (richiesto per Next.js 16)
  • Account Dodo Payments (per accedere alle chiavi API e Webhook dal dashboard)

​
Avvio Rapido

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

Iscriviti su Dodo Payments e ottieni le tue credenziali dalla dashboard:
Assicurati di essere in Modalità Test durante lo sviluppo!
4

Configure Environment Variables

Crea un file .env nella directory principale:
cp .env.example .env
Aggiorna i valori con le tue credenziali 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
Non includere mai il file .env nel controllo di versione. È già incluso in .gitignore.
5

Add Your Products

Aggiorna src/lib/products.ts con i tuoi ID prodotto effettivi da 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
Apri http://localhost:3000 per vedere la tua pagina dei prezzi!

​
Struttura del Progetto

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

​
Personalizzazione

​
Aggiorna le Informazioni sul Prodotto

Modifica src/lib/products.ts per aggiornare:
  • ID prodotto (dal tuo pannello Dodo)
  • Prezzi
  • Funzionalità
  • Descrizioni

​
Pre-compila i Dati del Cliente

In src/app/components/ProductCard.tsx, sostituisci i valori hardcoded con i dati reali dell’utente: 
customer: {
  name: "John Doe",
  email: "john@example.com",
},

​
Aggiorna il Portale Clienti

In src/app/components/Header.tsx, sostituisci l’ID cliente hardcoded: 
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
Puoi completare un acquisto di prova per ottenere l’ID cliente per il testing.

​
Eventi Webhook

Il boilerplate dimostra la gestione di due eventi webhook in src/app/api/webhook/route.ts:
  • onSubscriptionActive - Attivato quando un abbonamento diventa attivo
  • onPaymentSucceeded - Attivato quando un pagamento va a buon fine
Aggiungi la tua logica aziendale all’interno di questi gestori: 
onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},
Aggiungi ulteriori eventi webhook se necessario. Per lo sviluppo locale, puoi utilizzare strumenti come ngrok per creare un tunnel sicuro al tuo server locale e usarlo come URL del tuo webhook.

​
Distribuzione

​
Compila per la Produzione

npm run build
npm start

​
Distribuisci su Vercel

[ Distribuisci con Vercel ](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) Non dimenticare di aggiungere le tue variabili d’ambiente nel dashboard di Vercel!

​
Aggiorna l’URL del Webhook

Dopo la distribuzione, aggiorna il tuo URL del webhook nel Dashboard Dodo Payments: 
https://example.com/api/webhook

​
Risoluzione dei Problemi

Elimina node_modules e reinstalla le dipendenze:
rm -rf node_modules package-lock.json
npm install
Cause comuni:
  • ID prodotto non valido - verifica che esista nella tua dashboard Dodo
  • Chiave API errata o impostazione dell’ambiente sbagliata in .env
  • Controlla la console del browser e il terminale per eventuali errori
Per i test locali, utilizza ngrok per esporre il tuo server:
ngrok http 3000
Aggiorna l’URL del webhook nella tua dashboard Dodo con l’URL di ngrok. Ricorda di aggiornare il file .env con la chiave di verifica del webhook corretta.

​
Scopri di Più

​
Supporto

Hai bisogno di aiuto con il boilerplate?