计费 SDK

Billing SDK 是一组开源 React 计费组件，并配备可将项目连接到 Dodo Payments 的 CLI。该 CLI 会为你的框架生成 API 路由、React hook 和 Dodo Payments 客户端，并添加定价表和用量计量器等组件。

概述

Billing SDK 包括：

React Components：适用于 React 应用的预构建、可自定义计费组件。
CLI Tooling：用于初始化项目和添加组件的命令行界面。
Framework Support：支持 Next.js、Express.js、Hono、Fastify、NestJS 和 React 的模板。
Payment Provider：与 Dodo Payments 的完整集成。

快速开始

要在现有项目中设置 Billing SDK，请从项目根目录运行 CLI：

Install the CLI

使用 npx 运行 CLI，无需安装它：

npx @billingsdk/cli --help

如果经常使用，也可以全局安装。全局安装会添加 billingsdk 命令，例如 billingsdk init：

npm install -g @billingsdk/cli

Initialize a Project

运行交互式设置，将计费功能添加到项目中：

npx @billingsdk/cli init

CLI 会提示你选择：

你的框架：Next.js、Express.js、React、Hono、Fastify 或 NestJS。CLI 会检测你的框架，并将其标记为已检测到。
你的支付提供商：选择 Dodo Payments。

Add Components

将各个计费组件添加到您的项目：

npx @billingsdk/cli add pricing-table-one
npx @billingsdk/cli add subscription-management

支持的框架

Billing SDK 为以下每个框架提供了 Dodo Payments 模板：

Framework	Dodo Payments
Next.js	Yes
Express.js	Yes
Hono	Yes
React	Yes
Fastify	Yes
NestJS	Yes

CLI 命令

`@billingsdk/cli init`

init 会在项目中设置计费功能：它会安装带有 Dodo Payments 集成的框架模板，以及模板所需的依赖项。 它的功能：

Framework Selection：选择框架和支付提供商。
Template Installation：CLI 会从 Billing SDK registry 下载适用于框架和提供商的模板，并安装其中的文件。
Dependency Management：CLI 会使用 npm、pnpm、Yarn 或 Bun 安装模板依赖项，例如 dodopayments、standardwebhooks 和 zod。
File Generation：CLI 会写入配置文件和样板代码。对于 Express.js、Fastify、Hono 和 NestJS，这些文件会写入 src/。

示例：

npx @billingsdk/cli init

要在不显示提示的情况下运行 init，请传入 --framework、--provider 和 --yes，例如 npx @billingsdk/cli init --framework nextjs --provider dodopayments --yes。添加 --dry-run 可列出文件而不写入文件，添加 --no-install 可跳过依赖项安装，或添加 --package-manager 以选择 npm、pnpm、yarn 或 bun。

`@billingsdk/cli add`

add 通过 shadcn/ui registry 系统在项目中安装单个计费组件。它会使用包管理器的 runner 运行 shadcn@latest add @billingsdk/<component>。 示例：

# Add a pricing table
npx @billingsdk/cli add pricing-table-one

# Add subscription management
npx @billingsdk/cli add subscription-management

# Add usage monitoring
npx @billingsdk/cli add usage-meter-circle

执行结果：

shadcn CLI 会从 registry 下载组件配置。
它会将组件文件安装到 components/billingsdk/ 目录中。
如果需要，它会更新项目配置。
它会安装所有额外依赖项。

生成的文件结构

运行 init 后，项目中会包含：

API Routes：用于结账、客户、客户付款、产品、订阅和 webhooks 的端点。React 模板不包含 API 路由。
Hooks：用于计费操作的 useBilling React hook，适用于 React 和 Next.js。
Library Files：Dodo Payments 客户端设置和辅助函数，位于 lib/dodopayments.ts 中。
Environment Configuration：环境文件示例 .env.example。

Next.js 示例结构

对于 Next.js，init 会写入以下文件：

your-project/
├── app/api/
│   ├── checkout/route.ts
│   ├── customer/route.ts
│   ├── customer/payments/route.ts
│   ├── customer/subscriptions/route.ts
│   ├── product/route.ts
│   ├── products/route.ts
│   └── webhook/route.ts
├── hooks/
│   └── useBilling.ts
├── lib/
│   └── dodopayments.ts
└── .env.example

环境配置

初始化后，设置环境变量。从控制面板中的 Developer → API Keys 获取 API key，并从 Developer → Webhooks 获取 webhook key：

# DodoPayments
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here

# App URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

将 DODO_PAYMENTS_ENVIRONMENT 设置为 test_mode 或 live_mode。生成的 Dodo Payments 客户端对于任何其他值都会抛出错误。

将 API keys 存储在环境变量中。切勿将其提交到版本控制系统。

可用组件

Billing SDK 在以下类别中提供 React 组件：

Pricing Tables：八种变体，从 pricing-table-one 到 pricing-table-eight，用于显示产品定价。
Subscription Management：subscription-management，以及用于取消订阅或更新方案的卡片和对话框。
Usage Monitoring：圆形和线性用量计量器，以及用于基于用量计费的用量表格。
Checkout Components：支付方式选择器、付款详情表单和支付失败卡片。
Customer Portal：计费设置、计费页面、发票历史记录和即将产生的费用，供客户自助使用。

要浏览所有带实时预览的组件，请参阅组件库。

开源

Billing SDK 是开源项目：

透明性：你可以了解每个组件的工作方式。
社区：开发者为其他开发者构建它。
安全性：任何人都可以审查代码中的安全问题。
创新：社区贡献可以加快开发速度。

Billing SDK 根据 GNU General Public License v3.0 (GPL-3.0) 发布，该许可证确保项目保持开放和免费。

获取帮助

如需 Billing SDK 方面的帮助，请使用以下资源：

GitHub Issues：提交 issue
Documentation：访问 billingsdk.com/docs
LLMs Full Documentation：billingsdk.com/llms-full.txt

贡献

Billing SDK 欢迎贡献。贡献指南介绍了如何：

报告 bug
请求功能
提交 pull request
添加新组件
改进文档

了解更多

Full Documentation

Billing SDK 完整指南，包含示例和最佳实践

CLI Reference

涵盖所有命令和选项的详细 CLI 文档

Component Library

浏览所有可用组件及其实时示例

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

概述

快速开始

支持的框架

CLI 命令

`@billingsdk/cli init`

`@billingsdk/cli add`

生成的文件结构

Next.js 示例结构

环境配置

可用组件

开源

获取帮助

贡献

了解更多

Full Documentation

CLI Reference

Component Library

​概述

​快速开始

​支持的框架

​CLI 命令

​@billingsdk/cli init

​@billingsdk/cli add

​生成的文件结构

​Next.js 示例结构

​环境配置

​可用组件

​开源

​获取帮助

​贡献

​了解更多

Full Documentation

CLI Reference

Component Library

概述

快速开始

支持的框架

CLI 命令

`@billingsdk/cli init`

`@billingsdk/cli add`

生成的文件结构

Next.js 示例结构

环境配置

可用组件

开源

获取帮助

贡献

了解更多