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

> Starten Sie schnell mit unserem minimalen Astro-Boilerplate zur Integration von Dodo Payments in Ihre Astro-Anwendung

## Übersicht

Das Astro Minimal Boilerplate bietet einen sofort einsatzbereiten Ausgangspunkt für die Integration von Dodo Payments in Ihre Astro-Anwendung. Diese Vorlage umfasst Checkout-Sitzungen, Webhook-Verarbeitung, Kundenportal und moderne UI-Komponenten, um Ihnen zu helfen, schnell Zahlungen zu akzeptieren.

<Info>
  Dieser Boilerplate verwendet Astro 5 mit TypeScript, Tailwind CSS 4 und den `@dodopayments/astro` Adapter.
</Info>

### Funktionen

* **Schnellstart** – In weniger als 5 Minuten loslegen
* **Zahlungsintegration** – Vorgefertigter Checkout-Flow mit `@dodopayments/astro`
* **Moderne UI** – Saubere, dunkel gehaltene Preisseite mit Tailwind CSS
* **Webhook-Handler** – Bereit einsatzfähiger Webhook-Endpunkt für Zahlungsevents
* **Kundenportal** – Abonnementverwaltung mit einem Klick
* **TypeScript** – Vollständig typisiert mit minimalen, fokussierten Typen
* **Vorbefüllter Checkout** – Zeigt, wie Kundendaten übergeben werden, um die Nutzererfahrung zu verbessern

## Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

* **Node.js LTS-Version** (erforderlich für Astro 5)
* **Dodo Payments-Konto** (um API- und Webhook-Keys vom Dashboard abzurufen)

## Schnellstart

<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">
    Registriere dich bei [Dodo Payments](https://dodopayments.com/) und hole dir deine Zugangsdaten vom Dashboard:

    * **API-Schlüssel:** [Dashboard → Entwickler → API-Schlüssel](https://app.dodopayments.com/developer/api-keys)
    * **Webhook-Schlüssel:** [Dashboard → Entwickler → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Stelle sicher, dass du dich während der Entwicklung im **Testmodus** befindest!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Erstelle eine Datei `.env` im Stammverzeichnis:

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

    Aktualisieren Sie die Werte mit Ihren Dodo Payments-Anmeldeinformationen:

    ```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>
      Committe niemals deine Datei `.env` in die Versionskontrolle. Sie ist bereits in `.gitignore` enthalten.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    Aktualisiere `src/lib/products.ts` mit deinen tatsächlichen Produkt-IDs von 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
    ```

    Öffne [http://localhost:4321](http://localhost:4321), um deine Preisseite zu sehen!
  </Step>
</Steps>

## Projektstruktur

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

## Anpassung

### Produktinformationen aktualisieren

Bearbeite `src/lib/products.ts`, um folgende Elemente anzupassen:

* Produkt-IDs (aus deinem Dodo-Dashboard)
* Preise
* Funktionen
* Beschreibungen

### Kundendaten vorab ausfüllen

Ersetze in `src/components/ProductCard.astro` die fest codierten Werte durch deine tatsächlichen Benutzerdaten:

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

### Kundenportal aktualisieren

Ersetze in `src/components/Header.astro` die fest codierte Kunden-ID durch die tatsächliche Kunden-ID aus deinem Auth-System oder deiner Datenbank:

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

Sie können einen Testkauf abschließen, um die Kunden-ID für Tests zu erhalten.

## Webhook-Ereignisse

Die Boilerplate zeigt, wie man Webhook-Events in `src/pages/api/webhook.ts` verarbeitet:

* `onSubscriptionActive` – Wird ausgelöst, wenn ein Abonnement aktiv wird
* `onSubscriptionCancelled` – Wird ausgelöst, wenn ein Abonnement gekündigt wird

Fügen Sie Ihre Geschäftslogik in diese Handler ein:

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

Fügen Sie bei Bedarf weitere Webhook-Ereignisse hinzu.

Für die lokale Entwicklung können Sie Tools wie [ngrok](https://ngrok.com/) verwenden, um einen sicheren Tunnel zu Ihrem lokalen Server zu erstellen und ihn als Ihre Webhook-URL zu verwenden.

## Bereitstellung

Dieses Boilerplate verwendet statische Ausgaben mit bedarfsorientierter Rendering für API-Routen. Sie müssen einen Adapter für Ihre Bereitstellungsplattform installieren:

| Plattform  | Anleitung                                                                              |
| ---------- | -------------------------------------------------------------------------------------- |
| Vercel     | [Bereitstellung auf Vercel](https://docs.astro.build/en/guides/deploy/vercel/)         |
| Netlify    | [Bereitstellung auf Netlify](https://docs.astro.build/en/guides/deploy/netlify/)       |
| Cloudflare | [Bereitstellung auf Cloudflare](https://docs.astro.build/en/guides/deploy/cloudflare/) |

Siehe [Astros Bereitstellungsanleitungen](https://docs.astro.build/en/guides/deploy/) für alle Plattformen.

### Webhook-URL aktualisieren

Nach der Bereitstellung aktualisieren Sie Ihre Webhook-URL im [Dodo Payments Dashboard](https://app.dodopayments.com/developer/webhooks):

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

Denk auch daran, die Umgebungsvariable `DODO_PAYMENTS_WEBHOOK_KEY` in deiner Produktionsumgebung zu aktualisieren, damit sie mit dem Webhook-Signatur-Schlüssel deiner bereitgestellten Domain übereinstimmt.

## Fehlersuche

<AccordionGroup>
  <Accordion title="Module not found or build errors">
    Lösche `node_modules` und installiere die Abhängigkeiten neu:

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

  <Accordion title="Checkout redirect fails">
    **Häufige Ursachen:**

    * Ungültige Produkt-ID – überprüfe, ob sie in deinem Dodo-Dashboard existiert
    * Falscher API-Schlüssel oder Umgebungseinstellung in `.env`
    * Prüfe die Browser-Konsole und das Terminal auf Fehler
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    Für lokale Tests verwende [ngrok](https://ngrok.com), um deinen Server freizugeben:

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

    Aktualisiere die Webhook-URL in deinem [Dodo-Dashboard](https://app.dodopayments.com/developer/webhooks) auf die ngrok-URL. Denk daran, deine .env-Datei mit dem korrekten Webhook-Verifizierungsschlüssel zu aktualisieren.
  </Accordion>

  <Accordion title="Customer portal link doesn't work">
    Ersetze die fest codierte `CUSTOMER_ID` in `src/components/Header.astro` durch eine tatsächliche Kunden-ID aus deinem Dodo-Dashboard.

    Oder integriere dein Authentifizierungssystem und deine Datenbank, um die Kunden-ID dynamisch abzurufen.
  </Accordion>

  <Accordion title="Build fails with adapter error">
    Diese Boilerplate verwendet statische Ausgaben mit bedarfsorientierten API-Routen. Du musst einen Adapter für die Bereitstellung installieren:

    Siehe [Astro's Deployment-Guides](https://docs.astro.build/en/guides/deploy/) für Details.
  </Accordion>
</AccordionGroup>

## Erfahren Sie mehr

* [Dodo Payments Dokumentation](https://docs.dodopayments.com/)
* [Checkout Sessions Dokumentation](https://docs.dodopayments.com/developer-resources/checkout-session)
* [Webhooks Dokumentation](https://docs.dodopayments.com/developer-resources/webhooks)

## Unterstützung

Brauchen Sie Hilfe mit dem Boilerplate?

* Treten Sie unserer [Discord-Community](https://discord.gg/bYqAp4ayYh) für Fragen und Diskussionen bei
* Überprüfen Sie das [GitHub-Repository](https://github.com/dodopayments/dodo-astro-minimal-boilerplate) auf Probleme und Updates
* Kontaktieren Sie unser [Support-Team](mailto:support@dodopayments.com) für Unterstützung