> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js Minimal Boilerplate

> Inizia rapidamente con il nostro minimal Next.js boilerplate per integrare Dodo Payments nella tua applicazione Next.js

## 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.

<Info>
  Questo boilerplate utilizza Next.js 16 App Router con TypeScript, Tailwind CSS 4 e l'adapter `@dodopayments/nextjs`.
</Info>

### 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

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
    cd dodo-nextjs-minimal-boilerplate
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Get API Credentials">
    Iscriviti su [Dodo Payments](https://dodopayments.com/) e ottieni le tue credenziali dalla dashboard:

    * **API Key:** [Dashboard → Developer → API Keys](https://app.dodopayments.com/developer/api-keys)
    * **Webhook Key:** [Dashboard → Developer → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Assicurati di essere in **Modalità Test** durante lo sviluppo!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Crea un file `.env` nella directory principale:

    ```bash theme={null}
    cp .env.example .env
    ```

    Aggiorna i valori con le tue credenziali Dodo Payments:

    ```env theme={null}
    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
    ```

    <Warning>
      Non includere mai il file `.env` nel controllo di versione. È già incluso in `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    Aggiorna `src/lib/products.ts` con i tuoi ID prodotto effettivi da Dodo Payments:

    ```typescript theme={null}
    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
    ];
    ```
  </Step>

  <Step title="Run the Development Server">
    ```bash theme={null}
    npm run dev
    ```

    Apri [http://localhost:3000](http://localhost:3000) per vedere la tua pagina dei prezzi!
  </Step>
</Steps>

## Struttura del Progetto

```text theme={null}
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:

```typescript theme={null}
customer: {
  name: "John Doe",
  email: "john@example.com",
},
```

### Aggiorna il Portale Clienti

In `src/app/components/Header.tsx`, sostituisci l’ID cliente hardcoded:

```typescript theme={null}
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:

```typescript theme={null}
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](https://ngrok.com/) per creare un tunnel sicuro al tuo server locale e usarlo come URL del tuo webhook.

## Distribuzione

### Compila per la Produzione

```bash theme={null}
npm run build
npm start
```

### Distribuisci su Vercel

\[

![Distribuisci con Vercel](https://vercel.com/button)

]\([https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate](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://app.dodopayments.com/developer/webhooks):

```
https://example.com/api/webhook
```

## Risoluzione dei Problemi

<AccordionGroup>
  <Accordion title="Module not found or build errors">
    Elimina `node_modules` e reinstalla le dipendenze:

    ```bash theme={null}
    rm -rf node_modules package-lock.json
    npm install
    ```
  </Accordion>

  <Accordion title="Checkout redirect fails">
    **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
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    Per i test locali, utilizza [ngrok](https://ngrok.com) per esporre il tuo server:

    ```bash theme={null}
    ngrok http 3000
    ```

    Aggiorna l’URL del webhook nella tua [dashboard Dodo](https://app.dodopayments.com/developer/webhooks) con l’URL di ngrok. Ricorda di aggiornare il file .env con la chiave di verifica del webhook corretta.
  </Accordion>

  <Accordion title="Customer portal link doesn't work">
    Sostituisci l’`CUSTOMER_ID` hardcoded in `src/app/components/Header.tsx` con un ID cliente reale dalla tua dashboard Dodo.

    Oppure integra il tuo sistema di autenticazione e database per recuperare dinamicamente l’ID cliente.
  </Accordion>
</AccordionGroup>

## Scopri di Più

* [Documentazione Dodo Payments](https://docs.dodopayments.com/)
* [Documentazione delle sessioni di checkout](https://docs.dodopayments.com/developer-resources/checkout-session)
* [Documentazione Webhooks](https://docs.dodopayments.com/developer-resources/webhooks)

## Supporto

Hai bisogno di aiuto con il boilerplate?

* Unisciti alla nostra [comunità Discord](https://discord.gg/bYqAp4ayYh) per domande e discussioni
* Controlla il [repository GitHub](https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) per problemi e aggiornamenti
* Contatta il nostro [team di supporto](mailto:support@dodopayments.com) per assistenza