> ## 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 애플리케이션에 통합하기 위한 즉시 사용 가능한 시작점을 제공합니다. 이 템플릿에는 체크아웃 세션, 웹훅 처리, 고객 포털 및 결제를 빠르게 수락하는 데 도움이 되는 현대적인 UI 구성 요소가 포함되어 있습니다.

<Info>
  이 보일러플레이트는 Astro 5, TypeScript, Tailwind CSS 4 및 `@dodopayments/astro` 어댑터를 사용합니다.
</Info>

### 기능

* **빠른 설정** - 5분 이내에 시작
* **결제 통합** - `@dodopayments/astro`을 사용한 사전 구성된 체크아웃 흐름
* **현대적인 UI** - Tailwind CSS로 깔끔한 다크 테마 가격 페이지
* **웹훅 핸들러** - 결제 이벤트를 위한 즉시 사용 가능한 웹훅 엔드포인트
* **고객 포털** - 원클릭 구독 관리
* **TypeScript** - 최소한의 집중된 타입으로 완전 타이핑됨
* **사전 입력된 체크아웃** - UX를 개선하기 위해 고객 데이터를 전달하는 방법을 보여줌

## 필수 조건

시작하기 전에 다음을 확인하세요:

* **Node.js LTS 버전** (Astro 5에 필요)
* **Dodo Payments 계정** (대시보드에서 API 및 웹훅 키에 접근하기 위해)

## 빠른 시작

<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)
    * **웹훅 키:** [대시보드 → 개발자 → 웹훅](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를 얻기 위해 테스트 구매를 완료할 수 있습니다.

## 웹훅 이벤트

이 보일러플레이트는 `src/pages/api/webhook.ts`에서 웹훅 이벤트 처리를 보여줍니다:

* `onSubscriptionActive` - 구독이 활성화될 때 트리거
* `onSubscriptionCancelled` - 구독이 취소될 때 트리거

이 핸들러 내에 비즈니스 로직을 추가하세요:

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

필요에 따라 더 많은 웹훅 이벤트를 추가하세요.

로컬 개발을 위해 [ngrok](https://ngrok.com/)와 같은 도구를 사용하여 로컬 서버에 대한 보안 터널을 생성하고 이를 웹훅 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/)를 참조하세요.

### 웹훅 URL 업데이트

배포 후 [Dodo Payments 대시보드](https://app.dodopayments.com/developer/webhooks)에서 웹훅 URL을 업데이트하세요:

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

또한 배포된 도메인의 웹훅 서명 키에 맞게 생산 환경에서 `DODO_PAYMENTS_WEBHOOK_KEY` 환경 변수를 업데이트하는 것을 잊지 마세요.

## 문제 해결

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

    웹훅 URL을 [Dodo 대시보드](https://app.dodopayments.com/developer/webhooks)에서 ngrok URL로 업데이트하세요. 웹훅 검증 키를 .env 파일에 올바르게 반영하는 것도 기억하세요.
  </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 경로가 있는 정적 출력(static output)을 사용합니다. 배포를 위해 어댑터를 설치해야 합니다:

    자세한 내용은 [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)에게 연락하세요