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

> Dodo PaymentsをAstroアプリケーションに統合するための最小限のAstroボイラープレートで迅速に開始しましょう

## 概要

Astroの最小限のボイラープレートは、Dodo PaymentsをAstroアプリケーションに統合するためのすぐに使える出発点を提供します。このテンプレートには、チェックアウトセッション、Webhook処理、顧客ポータル、迅速に支払いを受け入れるためのモダンなUIコンポーネントが含まれています。

<Info>
  このボイラープレートは Astro 5 と TypeScript、Tailwind CSS 4、および `@dodopayments/astro` アダプターを使用しています。
</Info>

### 特徴

* **すばやくセットアップ** - 5 分以内に開始できます
* **決済統合** - `@dodopayments/astro` を使用した事前構成済みのチェックアウトフロー
* **モダンな UI** - Tailwind CSS を使ったシンプルでダークテーマの価格ページ
* **Webhook ハンドラー** - 決済イベント用のすぐに使える webhook エンドポイント
* **カスタマーポータル** - ワンクリックでのサブスクリプション管理
* **TypeScript** - 最小限で集中した型による完全な型付け
* **事前入力済みチェックアウト** - 顧客データを渡して UX を向上させるデモ

## 前提条件

始める前に、次のものを用意してください：

* **Node.js LTSバージョン**（Astro 5に必要）
* **Dodo Paymentsアカウント**（ダッシュボードからAPIおよびWebhookキーにアクセスするため）

## クイックスタート

<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">
    [Dodo Payments](https://dodopayments.com/) でサインアップし、ダッシュボードから認証情報を取得してください:

    * **APIキー:** [ダッシュボード → 開発者 → APIキー](https://app.dodopayments.com/developer/api-keys)
    * **Webhookキー:** [ダッシュボード → 開発者 → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      開発中は必ず **テストモード** にしてください！
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    プロジェクトルートに `.env` ファイルを作成してください:

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

    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>
      `.env` ファイルをバージョン管理にコミットしないでください。`.gitignore` にすでに含まれています。
    </Warning>
  </Step>

  <Step title="Add Your Products">
    `src/lib/products.ts` を、Dodo Payments から取得した実際の製品 ID に更新してください:

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

    [http://localhost:4321](http://localhost:4321) を開いて価格ページを確認してください！
  </Step>
</Steps>

## プロジェクト構造

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

## カスタマイズ

### 製品情報の更新

`src/lib/products.ts` を編集して、次を変更できます:

* 製品 ID（Dodo ダッシュボードから）
* 価格設定
* 機能
* 説明

### 顧客データの事前入力

`src/components/ProductCard.astro` では、ハードコードされた値を実際のユーザーデータに置き換えてください:

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

### 顧客ポータルの更新

`src/components/Header.astro` では、ハードコードされた顧客 ID を認証システムやデータベースの実際の顧客 ID に置き換えてください:

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

テスト用に顧客IDを取得するためにテスト購入を完了できます。

## Webhookイベント

このボイラープレートでは、`src/pages/api/webhook.ts` で webhook イベントを処理する方法を示しています:

* `onSubscriptionActive` - サブスクリプションがアクティブになったときにトリガーされます
* `onSubscriptionCancelled` - サブスクリプションがキャンセルされたときにトリガーされます

これらのハンドラー内にビジネスロジックを追加します：

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

必要に応じて、さらにWebhookイベントを追加します。

ローカル開発のために、[ngrok](https://ngrok.com/)のようなツールを使用して、ローカルサーバーへの安全なトンネルを作成し、それをWebhook URLとして使用できます。

## デプロイメント

このボイラープレートは、APIルートのオンデマンドレンダリングを伴う静的出力を使用します。デプロイメントプラットフォーム用のアダプターをインストールする必要があります：

| プラットフォーム   | ガイド                                                                      |
| ---------- | ------------------------------------------------------------------------ |
| Vercel     | [Vercelにデプロイ](https://docs.astro.build/en/guides/deploy/vercel/)         |
| Netlify    | [Netlifyにデプロイ](https://docs.astro.build/en/guides/deploy/netlify/)       |
| Cloudflare | [Cloudflareにデプロイ](https://docs.astro.build/en/guides/deploy/cloudflare/) |

すべてのプラットフォームの詳細については、[Astroのデプロイメントガイド](https://docs.astro.build/en/guides/deploy/)を参照してください。

### Webhook URLの更新

デプロイ後、[Dodo Paymentsダッシュボード](https://app.dodopayments.com/developer/webhooks)でWebhook URLを更新します：

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

また、本番環境では `DODO_PAYMENTS_WEBHOOK_KEY` 環境変数を、デプロイ先ドメインの webhook 署名キーと一致するように更新することを忘れないでください。

## トラブルシューティング

<AccordionGroup>
  <Accordion title="Module not found or build errors">
    `node_modules` を削除し、依存関係を再インストールしてください:

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

  <Accordion title="Checkout redirect fails">
    **一般的な原因:**

    * 無効な製品 ID - Dodo ダッシュボードで存在することを確認してください
    * `.env` の API キーまたは環境設定が間違っている
    * ブラウザのコンソールとターミナルでエラーを確認してください
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    ローカルテストでは、[ngrok](https://ngrok.com) を使ってサーバーを公開してください:

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

    [Dodo ダッシュボード](https://app.dodopayments.com/developer/webhooks) で webhook URL を ngrok URL に更新し、.env ファイルに正しい webhook 検証キーを設定してください。
  </Accordion>

  <Accordion title="Customer portal link doesn't work">
    `src/components/Header.astro` 内のハードコードされた `CUSTOMER_ID` を、Dodo ダッシュボードの実際の顧客 ID に置き換えてください。

    または、認証システムとデータベースを統合して顧客 ID を動的に取得してください。
  </Accordion>

  <Accordion title="Build fails with adapter error">
    このボイラープレートはオンデマンド API ルートを伴う静的出力を使用しています。デプロイにはアダプターのインストールが必要です:

    詳細については [Astro のデプロイガイド](https://docs.astro.build/en/guides/deploy/) をご覧ください。
  </Accordion>
</AccordionGroup>

## 詳細を学ぶ

* [Dodo Payments ドキュメント](https://docs.dodopayments.com/)
* [Checkout Sessions ドキュメント](https://docs.dodopayments.com/developer-resources/checkout-session)
* [Webhooks ドキュメント](https://docs.dodopayments.com/developer-resources/webhooks)

## サポート

ボイラープレートに関して助けが必要ですか？

* 質問や議論のために、[Discordコミュニティ](https://discord.gg/bYqAp4ayYh)に参加してください
* 問題や更新については、[GitHubリポジトリ](https://github.com/dodopayments/dodo-astro-minimal-boilerplate)を確認してください
* 支援が必要な場合は、[サポートチーム](mailto:support@dodopayments.com)に連絡してください