---
title: 框架整合指南
description: 選擇適合你專案的 Recur SDK 整合方式
---

## 選擇你的框架

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

  
    純 JavaScript，無框架依賴。適合靜態網站、WordPress、或任何環境。
  
  
    React 全端框架。支援 App Router、Server Actions、Route Handlers。
  
  
    內容優先的現代框架。支援 Islands Architecture、SSR、API Routes。
  

## 功能支援比較

| 功能 | 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

Recur 提供兩種 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（後端）

使用 **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 操作

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

## 下一步

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

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