# 框架整合指南 (/guides/frameworks)





選擇你的框架 [#選擇你的框架]

根據你的專案技術棧，選擇適合的整合指南：

<Cards>
  <Card title="Vanilla JS" href="/guides/frameworks/vanilla-js">
    純 JavaScript，無框架依賴。適合靜態網站、WordPress、或任何環境。
  </Card>

  <Card title="Next.js" href="/guides/frameworks/nextjs">
    React 全端框架。支援 App Router、Server Actions、Route Handlers。
  </Card>

  <Card title="Astro" href="/guides/frameworks/astro">
    內容優先的現代框架。支援 Islands Architecture、SSR、API Routes。
  </Card>
</Cards>

功能支援比較 [#功能支援比較]

| 功能                            | Vanilla JS |      Next.js     |      Astro      |
| ----------------------------- | :--------: | :--------------: | :-------------: |
| **Hosted Checkout**           |      ✅     |         ✅        |        ✅        |
| **Embedded Checkout (Modal)** |      ✅     |         ✅        |        ✅        |
| **Customer Portal**           |      ✅     |         ✅        |        ✅        |
| **Webhook 處理**                |     需後端    | ✅ Route Handlers | ✅ API Endpoints |
| **Server-Side Portal Link**   |     需後端    | ✅ Server Actions |   ✅ SSR/Hybrid  |
| **查詢訂閱狀態**                    |     需後端    |         ✅        |        ✅        |

安裝方式 [#安裝方式]

所有框架都使用相同的 npm 套件：

```bash
npm install recur-tw
```

或透過 CDN（適用於 Vanilla JS）：

```html
<script src="https://unpkg.com/recur-tw@latest/dist/recur.umd.js"></script>
```

兩種 SDK [#兩種-sdk]

Recur 提供兩種 SDK，根據你的使用情境選擇：

Client SDK（前端） [#client-sdk前端]

使用 **Publishable Key**（`pk_test_` 或 `pk_live_` 開頭），可安全暴露在前端：

```typescript
// React / Next.js
import { useRecur } from 'recur-tw';

const { redirectToCheckout } = useRecur();
await redirectToCheckout({
  productId: 'prod_xxx',
  successUrl: `${window.location.origin}/success`,
  cancelUrl: `${window.location.origin}/pricing`,
});

// Vanilla JS / CDN
const recur = RecurCheckout.init({ publishableKey: 'pk_test_xxx' });
await recur.redirectToCheckout({ ... });
```

**適用於：**

* 開啟結帳流程
* 顯示方案列表
* 前端互動功能

Server SDK（後端） [#server-sdk後端]

使用 **Secret Key**（`sk_test_` 或 `sk_live_` 開頭），**絕對不可暴露在前端**：

```typescript
import { Recur } from 'recur-tw/server';

const recur = new Recur(process.env.RECUR_SECRET_KEY!);

// 建立 Portal Session
const session = await recur.portal.sessions.create({
  customer: 'cus_xxx',
  returnUrl: 'https://yoursite.com/account',
});
```

**適用於：**

* 建立 Customer Portal 連結
* 查詢/管理訂閱
* 處理 Webhook
* 任何需要驗證的 API 操作

<Callout type="warn">
  **安全提醒**：Secret Key 只能在伺服器端使用。如果你的框架是純前端（如靜態網站），需要自行建立後端 API 來處理敏感操作。
</Callout>

下一步 [#下一步]

選擇你使用的框架，閱讀完整的整合指南：

* [Vanilla JS 整合指南](/guides/frameworks/vanilla-js)
* [Next.js 整合指南](/guides/frameworks/nextjs)
* [Astro 整合指南](/guides/frameworks/astro)