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

> Mulai dengan cepat menggunakan boilerplate Astro minimal kami untuk mengintegrasikan Dodo Payments ke dalam aplikasi Astro Anda

## Ikhtisar

Boilerplate Astro minimal menyediakan titik awal yang siap digunakan untuk mengintegrasikan Dodo Payments dengan aplikasi Astro Anda. Template ini mencakup sesi checkout, penanganan webhook, portal pelanggan, dan komponen UI modern untuk membantu Anda mulai menerima pembayaran dengan cepat.

<Info>
  Boilerplate ini menggunakan Astro 5 dengan TypeScript, Tailwind CSS 4, dan adapter `@dodopayments/astro`.
</Info>

### Fitur

* **Quick Setup** - Mulai dalam kurang dari 5 menit
* **Payment Integration** - Alur checkout yang telah dikonfigurasi sebelumnya menggunakan `@dodopayments/astro`
* **Modern UI** - Halaman harga bertema gelap yang bersih dengan Tailwind CSS
* **Webhook Handler** - Endpoint webhook siap pakai untuk event pembayaran
* **Customer Portal** - Manajemen langganan satu klik
* **TypeScript** - Sepenuhnya bertipe dengan tipe minimal dan fokus
* **Pre-filled Checkout** - Menunjukkan cara meneruskan data pelanggan untuk meningkatkan UX

## Prasyarat

Sebelum Anda mulai, pastikan Anda memiliki:

* **Node.js versi LTS** (diperlukan untuk Astro 5)
* **Akun Dodo Payments** (untuk mengakses API dan Kunci Webhook dari dasbor)

## Memulai dengan Cepat

<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">
    Daftar di [Dodo Payments](https://dodopayments.com/) dan dapatkan kredensial Anda dari dasbor:

    * **Kunci API:** [Dasbor → Pengembang → Kunci API](https://app.dodopayments.com/developer/api-keys)
    * **Kunci Webhook:** [Dasbor → Pengembang → Webhook](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Pastikan Anda berada dalam **Test Mode** saat mengembangkan!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Buat file `.env` di direktori root:

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

    Perbarui nilai dengan kredensial Dodo Payments Anda:

    ```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>
      Jangan pernah meng-commit file `.env` Anda ke kontrol versi. File tersebut sudah termasuk dalam `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    Perbarui `src/lib/products.ts` dengan ID produk Anda yang sebenarnya dari 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
    ```

    Buka [http://localhost:4321](http://localhost:4321) untuk melihat halaman harga Anda!
  </Step>
</Steps>

## Struktur Proyek

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

## Kustomisasi

### Perbarui Informasi Produk

Sunting `src/lib/products.ts` untuk mengubah:

* ID Produk (dari dasbor Dodo Anda)
* Harga
* Fitur
* Deskripsi

### Isi Data Pelanggan

Di `src/components/ProductCard.astro`, gantilah nilai yang dikodekan langsung dengan data pengguna Anda yang sebenarnya:

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

### Perbarui Portal Pelanggan

Di `src/components/Header.astro`, gantilah ID pelanggan yang dikodekan langsung dengan ID pelanggan aktual dari sistem otentikasi atau basis data Anda:

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

Anda dapat menyelesaikan pembelian uji untuk mendapatkan ID pelanggan untuk pengujian.

## Peristiwa Webhook

Boilerplate ini menunjukkan penanganan event webhook di `src/pages/api/webhook.ts`:

* `onSubscriptionActive` - Dipicu ketika sebuah langganan menjadi aktif
* `onSubscriptionCancelled` - Dipicu ketika sebuah langganan dibatalkan

Tambahkan logika bisnis Anda di dalam penangan ini:

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

Tambahkan lebih banyak peristiwa webhook sesuai kebutuhan.

Untuk pengembangan lokal, Anda dapat menggunakan alat seperti [ngrok](https://ngrok.com/) untuk membuat terowongan aman ke server lokal Anda dan menggunakannya sebagai URL webhook Anda.

## Penyebaran

Boilerplate ini menggunakan output statis dengan rendering sesuai permintaan untuk rute API. Anda perlu menginstal adapter untuk platform penyebaran Anda:

| Platform   | Panduan                                                                       |
| ---------- | ----------------------------------------------------------------------------- |
| Vercel     | [Deploy to Vercel](https://docs.astro.build/en/guides/deploy/vercel/)         |
| Netlify    | [Deploy to Netlify](https://docs.astro.build/en/guides/deploy/netlify/)       |
| Cloudflare | [Deploy to Cloudflare](https://docs.astro.build/en/guides/deploy/cloudflare/) |

Lihat [panduan penyebaran Astro](https://docs.astro.build/en/guides/deploy/) untuk semua platform.

### Perbarui URL Webhook

Setelah penyebaran, perbarui URL webhook Anda di [Dasbor Dodo Payments](https://app.dodopayments.com/developer/webhooks):

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

Juga ingat untuk memperbarui variabel lingkungan `DODO_PAYMENTS_WEBHOOK_KEY` di lingkungan produksi Anda agar sesuai dengan kunci penandatanganan webhook untuk domain yang Anda deploy.

## Pemecahan Masalah

<AccordionGroup>
  <Accordion title="Module not found or build errors">
    Hapus `node_modules` dan pasang kembali dependensi:

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

  <Accordion title="Checkout redirect fails">
    **Penyebab umum:**

    * ID produk tidak valid - pastikan ada di dasbor Dodo Anda
    * Kunci API atau pengaturan lingkungan yang salah di `.env`
    * Periksa konsol browser dan terminal untuk melihat kesalahan
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    Untuk pengujian lokal, gunakan [ngrok](https://ngrok.com) untuk mengekspos server Anda:

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

    Perbarui URL webhook di [dasbor Dodo Anda](https://app.dodopayments.com/developer/webhooks) ke URL ngrok. Ingat untuk memperbarui file .env Anda dengan kunci verifikasi webhook yang benar.
  </Accordion>

  <Accordion title="Customer portal link doesn't work">
    Ganti `CUSTOMER_ID` yang dikodekan langsung di `src/components/Header.astro` dengan ID pelanggan nyata dari dasbor Dodo Anda.

    Atau integrasikan sistem otentikasi dan basis data Anda untuk mengambil ID pelanggan secara dinamis.
  </Accordion>

  <Accordion title="Build fails with adapter error">
    Boilerplate ini menggunakan output statis dengan rute API sesuai permintaan. Anda perlu menginstal adapter untuk deployment:

    Lihat [panduan deployment Astro](https://docs.astro.build/en/guides/deploy/) untuk detail.
  </Accordion>
</AccordionGroup>

## Pelajari Lebih Lanjut

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

## Dukungan

Butuh bantuan dengan boilerplate?

* Bergabunglah dengan [komunitas Discord kami](https://discord.gg/bYqAp4ayYh) untuk pertanyaan dan diskusi
* Periksa [repositori GitHub](https://github.com/dodopayments/dodo-astro-minimal-boilerplate) untuk masalah dan pembaruan
* Hubungi [tim dukungan kami](mailto:support@dodopayments.com) untuk bantuan