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

> Commencez rapidement avec notre boilerplate minimal Astro pour intégrer Dodo Payments dans votre application Astro

## Aperçu

Le boilerplate minimal Astro fournit un point de départ prêt à l'emploi pour intégrer Dodo Payments avec votre application Astro. Ce modèle inclut des sessions de paiement, la gestion des webhooks, un portail client et des composants UI modernes pour vous aider à commencer à accepter des paiements rapidement.

<Info>
  Ce modèle utilise Astro 5 avec TypeScript, Tailwind CSS 4 et l'adaptateur `@dodopayments/astro`.
</Info>

### Caractéristiques

* **Configuration rapide** - Démarrez en moins de 5 minutes
* **Intégration de paiement** - Flux de paiement préconfiguré utilisant `@dodopayments/astro`
* **Interface moderne** - Page tarifaire épurée à thème sombre avec Tailwind CSS
* **Gestionnaire de webhook** - Point de terminaison webhook prêt à l'emploi pour les événements de paiement
* **Portail client** - Gestion des abonnements en un clic
* **TypeScript** - Entièrement typé avec des types minimaux et ciblés
* **Paiement pré-rempli** - Montre comment transmettre les données client pour améliorer l'expérience utilisateur

## Prérequis

Avant de commencer, assurez-vous d'avoir :

* **Version LTS de Node.js** (nécessaire pour Astro 5)
* **Compte Dodo Payments** (pour accéder aux clés API et Webhook depuis le tableau de bord)

## Démarrage Rapide

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

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

  <Step title="Get API Credentials">
    Inscrivez-vous sur [Dodo Payments](https://dodopayments.com/) et récupérez vos identifiants depuis le tableau de bord :

    * **Clé API :** [Tableau de bord → Développeur → Clés API](https://app.dodopayments.com/developer/api-keys)
    * **Clé Webhook :** [Tableau de bord → Développeur → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Assurez-vous d'être en **mode Test** pendant le développement !
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Créez un fichier `.env` dans le répertoire racine :

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

    Mettez à jour les valeurs avec vos identifiants 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
    ```

    <Warning>
      Ne commettez jamais votre fichier `.env` dans le contrôle de version. Il est déjà inclus dans `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    Mettez à jour `src/lib/products.ts` avec vos identifiants de produit réels de 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
    ```

    Ouvrez [http://localhost:4321](http://localhost:4321) pour voir votre page tarifaire !
  </Step>
</Steps>

## Structure du Projet

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

## Personnalisation

### Mettre à Jour les Informations sur les Produits

Modifiez `src/lib/products.ts` pour changer :

* Identifiants de produit (depuis votre tableau de bord Dodo)
* Tarifs
* Fonctionnalités
* Descriptions

### Pré-remplir les Données Client

Dans `src/components/ProductCard.astro`, remplacez les valeurs codées en dur par vos données utilisateur réelles :

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

### Mettre à Jour le Portail Client

Dans `src/components/Header.astro`, remplacez l'ID client codé en dur par l'ID client réel provenant de votre système d'authentification ou de votre base de données :

```typescript theme={null}
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
```

Vous pouvez effectuer un achat test pour obtenir l'identifiant client pour les tests.

## Événements Webhook

Le modèle montre la gestion des événements webhook dans `src/pages/api/webhook.ts` :

* `onSubscriptionActive` - Déclenché lorsqu'un abonnement devient actif
* `onSubscriptionCancelled` - Déclenché lorsqu'un abonnement est annulé

Ajoutez votre logique métier à l'intérieur de ces gestionnaires :

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

Ajoutez d'autres événements webhook si nécessaire.

Pour le développement local, vous pouvez utiliser des outils comme [ngrok](https://ngrok.com/) pour créer un tunnel sécurisé vers votre serveur local et l'utiliser comme votre URL de webhook.

## Déploiement

Ce boilerplate utilise une sortie statique avec un rendu à la demande pour les routes API. Vous devrez installer un adaptateur pour votre plateforme de déploiement :

| Plateforme | Guide                                                                            |
| ---------- | -------------------------------------------------------------------------------- |
| Vercel     | [Déployer sur Vercel](https://docs.astro.build/en/guides/deploy/vercel/)         |
| Netlify    | [Déployer sur Netlify](https://docs.astro.build/en/guides/deploy/netlify/)       |
| Cloudflare | [Déployer sur Cloudflare](https://docs.astro.build/en/guides/deploy/cloudflare/) |

Consultez les [guides de déploiement d'Astro](https://docs.astro.build/en/guides/deploy/) pour toutes les plateformes.

### Mettre à Jour l'URL du Webhook

Après le déploiement, mettez à jour votre URL de webhook dans le [Tableau de bord Dodo Payments](https://app.dodopayments.com/developer/webhooks) :

```text theme={null}
https://your-domain.com/api/webhook
```

N'oubliez pas non plus de mettre à jour la variable d'environnement `DODO_PAYMENTS_WEBHOOK_KEY` dans votre environnement de production pour qu'elle corresponde à la clé de signature webhook de votre domaine déployé.

## Dépannage

<AccordionGroup>
  <Accordion title="Module not found or build errors">
    Supprimez `node_modules` et réinstallez les dépendances :

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

  <Accordion title="Checkout redirect fails">
    **Causes courantes :**

    * ID du produit invalide - vérifiez qu'il existe dans votre tableau de bord Dodo
    * Mauvaise clé API ou mauvais paramètre d'environnement dans `.env`
    * Vérifiez la console du navigateur et le terminal pour les erreurs
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    Pour les tests locaux, utilisez [ngrok](https://ngrok.com) pour exposer votre serveur :

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

    Mettez à jour l'URL du webhook dans votre [tableau de bord Dodo](https://app.dodopayments.com/developer/webhooks) avec l'URL ngrok. Pensez à mettre à jour votre fichier .env avec la clé de vérification webhook appropriée.
  </Accordion>

  <Accordion title="Customer portal link doesn't work">
    Remplacez l'`CUSTOMER_ID` codée en dur dans `src/components/Header.astro` par un ID client réel provenant de votre tableau de bord Dodo.

    Ou intégrez votre système d'authentification et votre base de données pour récupérer dynamiquement l'ID client.
  </Accordion>

  <Accordion title="Build fails with adapter error">
    Ce modèle utilise une sortie statique avec des routes API à la demande. Vous devez installer un adaptateur pour le déploiement :

    Consultez [les guides de déploiement d'Astro](https://docs.astro.build/en/guides/deploy/) pour plus de détails.
  </Accordion>
</AccordionGroup>

## En Savoir Plus

* [Documentation Dodo Payments](https://docs.dodopayments.com/)
* [Documentation des sessions de paiement](https://docs.dodopayments.com/developer-resources/checkout-session)
* [Documentation des webhooks](https://docs.dodopayments.com/developer-resources/webhooks)

## Support

Besoin d'aide avec le boilerplate ?

* Rejoignez notre [communauté Discord](https://discord.gg/bYqAp4ayYh) pour des questions et des discussions
* Consultez le [référentiel GitHub](https://github.com/dodopayments/dodo-astro-minimal-boilerplate) pour les problèmes et les mises à jour
* Contactez notre [équipe de support](mailto:support@dodopayments.com) pour assistance