> ## 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.
# Astro Minimal Boilerplate
> Inizia rapidamente con il nostro boilerplate Astro minimale per integrare Dodo Payments nella tua applicazione Astro
## Panoramica
Il boilerplate Astro minimale fornisce un punto di partenza pronto all'uso per integrare Dodo Payments con la tua applicazione Astro. Questo template include sessioni di checkout, gestione dei webhook, portale clienti e componenti UI moderni per aiutarti ad accettare pagamenti rapidamente.
Questo boilerplate utilizza Astro 5 con TypeScript, Tailwind CSS 4 e l’adapter `@dodopayments/astro`.
### Caratteristiche
* **Configurazione rapida** - Inizia in meno di 5 minuti
* **Integrazione pagamenti** - Flusso di checkout preconfigurato con `@dodopayments/astro`
* **UI moderna** - Pagina prezzi pulita e a tema scuro con Tailwind CSS
* **Gestore webhook** - Endpoint webhook pronto all’uso per gli eventi di pagamento
* **Portale clienti** - Gestione abbonamenti con un clic
* **TypeScript** - Tipizzazione completa con tipi minimi e mirati
* **Checkout precompilato** - Mostra come passare i dati del cliente per migliorare l’esperienza utente
## Requisiti
Prima di iniziare, assicurati di avere:
* **Versione LTS di Node.js** (richiesta per Astro 5)
* **Account Dodo Payments** (per accedere alle chiavi API e Webhook dal dashboard)
## Avvio Rapido
```bash theme={null}
git clone https://github.com/dodopayments/dodo-astro-minimal-boilerplate.git
cd dodo-astro-minimal-boilerplate
```
```bash theme={null}
npm install
```
Iscriviti a [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)
Assicurati di essere in **Modalità Test** durante lo sviluppo!
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:4321/
DODO_PAYMENTS_ENVIRONMENT=test_mode
```
Non inserire mai il tuo file `.env` nel controllo versione. È già incluso in `.gitignore`.
Aggiorna `src/lib/products.ts` con i tuoi ID prodotto reali 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
];
```
```bash theme={null}
npm run dev
```
Apri [http://localhost:4321](http://localhost:4321) per vedere la tua pagina prezzi!
## Struttura del Progetto
```text theme={null}
src/
├── components/
│ ├── Footer.astro # Reusable footer
│ ├── Header.astro # Navigation header
│ └── ProductCard.astro # Product pricing card
├── layouts/
│ └── Layout.astro # Root layout
├── lib/
│ └── products.ts # Product definitions
├── pages/
│ ├── index.astro # Pricing page (home)
│ └── api/
│ ├── checkout.ts # Checkout session handler
│ ├── customer-portal.ts # Customer portal redirect
│ └── webhook.ts # Webhook event handler
└── styles/
└── global.css # Global styles with Tailwind
```
## Personalizzazione
### Aggiorna le Informazioni sul Prodotto
Modifica `src/lib/products.ts` per aggiornare:
* ID prodotto (dalla tua dashboard Dodo)
* Prezzi
* Funzionalità
* Descrizioni
### Pre-compila i Dati del Cliente
In `src/components/ProductCard.astro`, sostituisci i valori hardcoded con i dati reali del tuo utente:
```typescript theme={null}
customer: {
name: "John Doe",
email: "john@example.com",
},
```
### Aggiorna il Portale Clienti
In `src/components/Header.astro`, sostituisci l’ID cliente hardcoded con l’ID cliente reale del tuo sistema di autenticazione o database:
```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 degli eventi webhook in `src/pages/api/webhook.ts`:
* `onSubscriptionActive` - Attivato quando un abbonamento diventa attivo
* `onSubscriptionCancelled` - Attivato quando un abbonamento viene annullato
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
Questo boilerplate utilizza output statico con rendering on-demand per le rotte API. Dovrai installare un adapter per la tua piattaforma di distribuzione:
| Piattaforma | Guida |
| ----------- | ----------------------------------------------------------------------------------- |
| Vercel | [Distribuisci su Vercel](https://docs.astro.build/en/guides/deploy/vercel/) |
| Netlify | [Distribuisci su Netlify](https://docs.astro.build/en/guides/deploy/netlify/) |
| Cloudflare | [Distribuisci su Cloudflare](https://docs.astro.build/en/guides/deploy/cloudflare/) |
Consulta le [guide alla distribuzione di Astro](https://docs.astro.build/en/guides/deploy/) per tutte le piattaforme.
### Aggiorna l'URL del Webhook
Dopo la distribuzione, aggiorna il tuo URL del webhook nel [Dashboard di Dodo Payments](https://app.dodopayments.com/developer/webhooks):
```text theme={null}
https://your-domain.com/api/webhook
```
Ricorda anche di aggiornare la variabile d’ambiente `DODO_PAYMENTS_WEBHOOK_KEY` nel tuo ambiente di produzione per abbinare la chiave di firma webhook per il dominio distribuito.
## Risoluzione dei Problemi
Elimina `node_modules` e reinstalla le dipendenze:
```bash theme={null}
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 ambiente sbagliata in `.env`
* Controlla la console del browser e il terminale per gli errori
Per i test locali, usa [ngrok](https://ngrok.com) per esporre il tuo server:
```bash theme={null}
ngrok http 4321
```
Aggiorna l’URL del webhook nella tua [dashboard Dodo](https://app.dodopayments.com/developer/webhooks) con l’URL ngrok. Ricorda di aggiornare il file .env con la chiave di verifica webhook corretta.
Sostituisci l’hardcoded `CUSTOMER_ID` in `src/components/Header.astro` con un ID cliente reale dalla tua dashboard Dodo.
Oppure integra il tuo sistema di autenticazione e database per recuperare dinamicamente l’ID cliente.
Questo boilerplate usa output statico con API routes on-demand. È necessario installare un adapter per la distribuzione:
Consulta le [guide di distribuzione di Astro](https://docs.astro.build/en/guides/deploy/) per i dettagli.
## Scopri di Più
* [Documentazione Dodo Payments](https://docs.dodopayments.com/)
* [Documentazione sulle sessioni di pagamento](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-astro-minimal-boilerplate) per problemi e aggiornamenti
* Contatta il nostro [team di supporto](mailto:support@dodopayments.com) per assistenza