Next.js Minimal Boilerplate

Panoramica

Il boilerplate minimo di Next.js è un’app starter con Dodo Payments già collegato. Aggiungi le tue chiavi API e gli ID prodotto per ottenere una pagina dei prezzi che apre il checkout, un endpoint webhook per gli eventi di pagamento e un link al Customer Portal.

Questo boilerplate utilizza l’App Router di Next.js 16 con TypeScript, Tailwind CSS 4 e l’adaptor @dodopayments/nextjs. Per aggiungere gli stessi route handler a un’app esistente, consulta Next.js Adaptor.

Caratteristiche

Il boilerplate include:

Configurazione rapida: passa dal clone a una pagina dei prezzi funzionante in circa cinque minuti.
Checkout: un flusso di checkout preconfigurato basato su @dodopayments/nextjs.
Pagina dei prezzi: una pagina dei prezzi con tema scuro e stile basato su Tailwind CSS.
Webhook Handler: un endpoint che verifica la firma di ogni webhook ed esegue il tuo codice per l’evento.
Customer Portal: un link nell’intestazione che apre il Customer Portal, dove i clienti gestiscono i loro abbonamenti.
TypeScript: definizioni dei prodotti e handler tipizzati.
Checkout precompilato: passa il nome e l’email del cliente al checkout, così il cliente non deve reinserirli.

Prerequisiti

Prima di iniziare, ti servono:

Node.js 20.9 o versione successiva, richiesto da Next.js 16.
Un account Dodo Payments, per creare una chiave API e un webhook signing secret nella dashboard.

Avvio rapido

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

Registrati su Dodo Payments, quindi recupera le tue credenziali dalla dashboard:

API Key: crea una chiave in Dashboard → Developer → API Keys.
Webhook Key: aggiungi un endpoint in Dashboard → Developer → Webhooks, quindi copia il suo signing secret. L’URL dell’endpoint deve essere pubblico e utilizzare HTTPS. Per ricevere eventi sul tuo computer, consulta Webhook Events.

Crea entrambi mentre l’interruttore Live Mode nella barra laterale è disattivato. Una chiave in modalità test funziona solo con DODO_PAYMENTS_ENVIRONMENT=test_mode e i pagamenti in modalità test non trasferiscono denaro reale.

Configure Environment Variables

Copia il file di esempio per creare un file .env nella directory principale:

cp .env.example .env

Imposta i valori usando 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

I route handler leggono queste variabili:

DODO_PAYMENTS_API_KEY autentica i gestori del checkout e del Customer Portal.
DODO_PAYMENTS_WEBHOOK_KEY verifica le firme dei webhook.
DODO_PAYMENTS_RETURN_URL indica dove il checkout reindirizza il cliente dopo il pagamento.
DODO_PAYMENTS_ENVIRONMENT è test_mode o live_mode.

Non eseguire il commit del file .env nel controllo versione. Il file .gitignore del repository lo esclude già.

Add Your Products

Sostituisci i prodotti di esempio in src/lib/products.ts con i tuoi. Imposta ogni product_id sull’ID di un prodotto nella sezione Products della 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 pagina dei prezzi mostra name, description, price e features da questo file. Il checkout addebita il prezzo impostato sul prodotto in Dodo Payments, quindi mantieni price sincronizzato con esso.

Run the Development Server

npm run dev

Apri http://localhost:3000 per visualizzare la tua pagina dei prezzi.

Struttura del progetto

I route handler per il checkout, il Customer Portal e i webhook si trovano in 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

Personalizzazione

Aggiornare le informazioni dei prodotti

Modifica src/lib/products.ts per cambiare:

ID prodotto, dalla sezione Products della dashboard Dodo Payments
Prezzi
Funzionalità
Descrizioni

Precompilare i dati del cliente

src/app/components/ProductCard.tsx invia un nome e un’email codificati direttamente in ogni richiesta di checkout. Sostituiscili con i dati dell’utente autenticato:

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

Aggiornare il Customer Portal

Il link Customer Portal in src/app/components/Header.tsx apre /api/customer-portal con un ID cliente codificato direttamente. Sostituiscilo con l’ID cliente Dodo Payments dell’utente autenticato:

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

Per ottenere un ID cliente a scopo di test, completa un acquisto di prova, quindi copia l’ID del cliente dalla sezione Customers nella dashboard. In produzione, recupera l’ID dal tuo backend.

Eventi webhook

Il gestore in src/app/api/webhook/route.ts verifica ogni richiesta con DODO_PAYMENTS_WEBHOOK_KEY, quindi gestisce due eventi:

onSubscriptionActive viene eseguito quando un abbonamento diventa attivo (subscription.active).
onPaymentSucceeded viene eseguito quando un pagamento va a buon fine (payment.succeeded).

Aggiungi la tua logica di business all’interno di questi handler:

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

Per gestire altri eventi, aggiungi i relativi handler, ad esempio onSubscriptionCancelled. Next.js Adaptor elenca tutti gli handler supportati. Dodo Payments non può raggiungere localhost. Per lo sviluppo locale, usa un tunnel come ngrok per esporre il tuo server locale e utilizza l’URL del tunnel come endpoint webhook.

Deployment

Creare una build per la produzione

npm run build
npm start

Eseguire il deployment su Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) Aggiungi le quattro variabili d’ambiente nella dashboard di Vercel e imposta DODO_PAYMENTS_RETURN_URL sull’URL di produzione.

Aggiornare l’URL del webhook

Dopo il deployment, aggiungi l’URL del webhook di produzione nella Dodo Payments Dashboard, sostituendo example.com con il tuo dominio:

https://example.com/api/webhook

Ogni endpoint ha il proprio signing secret. Copia il secret del nuovo endpoint in DODO_PAYMENTS_WEBHOOK_KEY nel tuo ambiente di produzione.

Risoluzione dei problemi

Module not found or build errors

Elimina node_modules e package-lock.json, quindi reinstalla le dipendenze:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Verifica queste cause comuni:

L’ID prodotto non esiste nella dashboard Dodo Payments.
La chiave API o DODO_PAYMENTS_ENVIRONMENT in .env non è corretta. Una chiave in modalità test funziona solo con test_mode.

Cerca l’errore nella console del browser e nel terminale che esegue npm run dev.

Webhooks not receiving events

Per i test locali, usa ngrok per esporre il tuo server:

ngrok http 3000

Nel tuo Dodo dashboard, aggiungi un endpoint con l’URL HTTPS di ngrok seguito da /api/webhook. Copia il signing secret di quell’endpoint in DODO_PAYMENTS_WEBHOOK_KEY nel tuo file .env.

Customer portal link doesn't work

Sostituisci l’CUSTOMER_ID codificato direttamente in src/app/components/Header.tsx con l’ID di un cliente nella dashboard Dodo Payments.In produzione, recupera invece l’ID cliente dal tuo sistema di autenticazione e dal database.

Per saperne di più

Documentazione di Dodo Payments
Documentazione sulle Checkout Sessions
Documentazione sui webhook
Next.js Adaptor: opzioni per i gestori Checkout, CustomerPortal e Webhooks

Supporto

Per ricevere assistenza sul boilerplate:

Fai domande nella community Discord.
Segnala problemi e segui gli aggiornamenti nel repository GitHub.
Scrivi al team di supporto.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Panoramica

Caratteristiche

Prerequisiti

Avvio rapido

Struttura del progetto

Personalizzazione

Aggiornare le informazioni dei prodotti

Precompilare i dati del cliente

Aggiornare il Customer Portal

Eventi webhook

Deployment

Creare una build per la produzione

Eseguire il deployment su Vercel

Aggiornare l’URL del webhook

Risoluzione dei problemi

Per saperne di più

Supporto

​Panoramica

​Caratteristiche

​Prerequisiti

​Avvio rapido

​Struttura del progetto

​Personalizzazione

​Aggiornare le informazioni dei prodotti

​Precompilare i dati del cliente

​Aggiornare il Customer Portal

​Eventi webhook

​Deployment

​Creare una build per la produzione

​Eseguire il deployment su Vercel

​Aggiornare l’URL del webhook

​Risoluzione dei problemi

​Per saperne di più

​Supporto

Panoramica

Caratteristiche

Prerequisiti

Avvio rapido

Struttura del progetto

Personalizzazione

Aggiornare le informazioni dei prodotti

Precompilare i dati del cliente

Aggiornare il Customer Portal

Eventi webhook

Deployment

Creare una build per la produzione

Eseguire il deployment su Vercel

Aggiornare l’URL del webhook

Risoluzione dei problemi

Per saperne di più

Supporto