---

The 单体仓库

嗨 👋，Storecraft 让开发者能够使用 TypeScript 和 JavaScript 快速构建由 AI 驱动的无头电子商务后端。

⭐ 以 AI 为先，具备代理功能、聊天端点和相似性搜索，可为您的客户及团队提供服务。我们支持大多数流行的 LLM 和用于相似性搜索的向量存储。

⭐ 通过强大的可编程 API 代码、REST API 和 VQL（虚拟查询语言）来管理产品、系列、订单、客户、认证、邮件等，并实现强大的查询与相似性搜索。

⭐ 内置聊天端点，配备代理功能，可为客户提供购物车、结账等服务，并支持 PayPal 和 Stripe 支付。

⭐ 可在任何 JavaScript 平台 上运行（Deno、Bun、Node、Cloudflare Workers、AWS Lambda、Google Functions 等），无论是无服务器还是传统服务器架构。

⭐ 可连接到任何 数据库（Mongo、LibSQL、SQLite、PostgreSQL、MySQL、Neon、Turso、D1、PlanetScale 等）。

⭐ 支持多种 存储 方式（本地存储、R2、S3 兼容存储、Google 存储等）。

⭐ 具有 可扩展性和模块化 特性。

⭐ 基于 事件驱动 架构。

⭐ 拥有官方 仪表板。

⭐ 文档完善 REST-API（也可在 /api/reference 端点中找到）。

---

立即使用 CLI 开始 👇

npx storecraft create

这是您开始构建自己的 Storecraft 应用所需的全部代码。

const app = new App({
  auth_admins_emails: ['tomer.shalev@gmail.com'],
  general_store_name: 'Wush Wush Games',
  // ... 更多必填配置
})
.withPlatform(new NodePlatform())
.withDatabase(new LibSQL())
.withStorage(new NodeLocalStorage('storage'))
.withMailer(new Resend())
.withPaymentGateways({
  paypal: new Paypal({ env: 'test' }),
  stripe: new Stripe(),
  dummy_payments: new DummyPayments(),
})
.withExtensions({
  postman: new PostmanExtension(),
})
.withAI(
  new OpenAI({ model: 'gpt-4o-mini'})
)
.withVectorStore(
  new LibSQLVectorStore({
    embedder: new OpenAIEmbedder(),
  })
)
.withAuthProviders({
  google: new GoogleAuth(),
})
.on(
  'order/checkout/complete',
  async (event) => {
    // 发送团队 Slack 消息
  }
).init();

await migrateToLatest(app._.db, false);
await app._.vector_store?.createVectorIndex();

http
.createServer(app.handler)
.listen(
  8000,
  () => {
    app.print_banner('http://localhost:8000');
  }
); 

将生成一个服务器

---

与 storeraft AI 代理聊天

位于 /chat

---

---

仪表板

位于 /dashboard

---

API 参考

位于 /api（由 Scalar 提供支持）

---

CLI（npx storecraft create）

---

如 MongoDB TV 直播所示

开发

这是一个单体仓库，packages 文件夹中的每个子文件夹都是一个独立的包，已发布至 @npm。它利用了 npm 的工作区功能。

要开始开发某个功能，请先执行以下命令：

npm install

以下是各包的布局：

Core (@storecraft/core)

Storecraft 的核心引擎

• 核心类型
• 核心 API
• 核心数据库类型
• 核心加密类型
• 核心存储类型
• 核心邮件类型
• 核心支付类型
• 核心平台类型
• 核心 VQL 类型及逻辑
• 核心 REST API 控制器

🌐 平台 @storecraft/core/platform

支持：

• Node
• Deno
• Bun
• Cloudflare Workers
• AWS Lambda
• Azure Functions
• Google Functions

💾 数据库

支持：

• MongoDB（@storecraft/database-mongo-node）
• SQLite（@storecraft/database-sqlite）
• Postgres（@storecraft/database-postgres）
• MySQL（@storecraft/database-mysql）
• SQL Base（@storecraft/database-sql-base）
• Neon（云Postgres，@storecraft/database-neon）
• PlanetScale（云MySQL，@storecraft/database-planetscale）
• Turso / Libsql（本地及云SQLite，@storecraft/database-turso）
• D1（云SQLite，@storecraft/database-cloudflare-d1）

📦 存储

支持：

• 本地存储（Node、Bun、Deno），@storecraft/core/storage
• S3 兼容存储（@storecraft/storage-s3-compatible）
  • Cloudflare R2
  • AWS S3
  • DigitalOcean Spaces
  • MinIO
• Google Storage（@storecraft/storage-google）

📧 邮件服务提供商

• HTTP 邮件服务 @storecraft/mailer-providers-http
  • 支持 Mailchimp
  • 支持 Mailgun
  • 支持 Resend
  • 支持 Sendgrid
• Node SMTP 支持 @storecraft/mailer-smtp

💳 支付

• Stripe @storecraft/payments-stripe
• PayPal @storecraft/payments-paypal
• 您也可以自行实现（指南 在此）

控制台

官方控制台

• 使用方法 在此
• 源码 在此，
  • 可作为组件挂载，或
  • 通过 CDN 引用

聊天

官方聊天功能

• 使用方法 在此
• 源码 在此，
  • 可作为组件挂载，或
  • 通过 CDN 引用

SDKs

• 通用（前后端）JavaScript SDK，@storecraft/sdk
• React Hooks SDK，@storecraft/sdk-react-hooks

测试运行器

使用以下工具测试您的应用、数据库、存储及其他集成：

@storecraft/core/test-runner

文档

文档网站源码 在此

CLI

npx storecraft create

CLI 源码 在此

示例游乐场

在此

发布流程

版本管理和发布以 monorepo 版本为准。所有已发布的包都会同步到 monorepo 版本。monorepo 源代码中的包可能版本不同，但这对已发布的包没有影响。

版本管理

所有版本都会同步到 monorepo 版本，并发布到 npm。执行以下命令之一：

npm run release:version:patch
npm run release:version:minor
npm run release:version:major

这些命令将：

• 仅更新 monorepo 的版本号；
• 添加对应版本的 Git 标签。

发布

当运行以下命令时：

npm run release:publish

它会：

• 将 monorepo 中所有包的版本更新为与 monorepo 相同的版本；
• 将所有包以与 monorepo 相同的版本发布到 npm。

这一过程可以在 CI/CD 流水线中自动完成，也可手动操作。

作者：托梅尔·沙列夫（tomer.shalev@gmail.com）

Storecraft 快速上手指南

Storecraft 是一个基于 TypeScript/JavaScript 的无头（Headless）电商后端框架，主打 AI 优先架构。它支持快速构建具备智能客服、相似性搜索、全渠道支付及多数据库适配能力的电商系统。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Windows, macOS 或 Linux
• 运行时环境: 需安装以下任一 JavaScript/TypeScript 运行时：
  • Node.js (推荐 LTS 版本)
  • Bun
  • Deno
  • Cloudflare Workers 环境
• 包管理器: npm, yarn, pnpm 或 bun
• 前置知识: 熟悉 TypeScript 或 JavaScript 基础语法

提示：虽然原文未提及国内镜像，但在中国大陆开发时，建议配置 npm 镜像源（如淘宝镜像）以加速依赖下载：

npm config set registry https://registry.npmmirror.com

安装步骤

Storecraft 提供了命令行工具（CLI）来快速初始化项目。

1. 创建新项目 在终端中运行以下命令，按照提示完成项目初始化：

   npx storecraft create
   

2. 安装依赖 进入生成的项目目录并安装依赖（如果 CLI 未自动执行）：

   npm install
   

基本使用

Storecraft 的核心在于通过代码配置应用实例。以下是一个最小化的服务端启动示例，展示了如何配置平台、数据库、存储、支付网关及 AI 功能。

创建一个入口文件（例如 index.ts 或 server.ts），填入以下代码：

const app = new App({
  auth_admins_emails: ['tomer.shalev@gmail.com'],
  general_store_name: 'Wush Wush Games',
  // ... MORE Mandatory CONFIG
})
.withPlatform(new NodePlatform())
.withDatabase(new LibSQL())
.withStorage(new NodeLocalStorage('storage'))
.withMailer(new Resend())
.withPaymentGateways({
  paypal: new Paypal({ env: 'test' }),
  stripe: new Stripe(),
  dummy_payments: new DummyPayments(),
})
.withExtensions({
  postman: new PostmanExtension(),
})
.withAI(
  new OpenAI({ model: 'gpt-4o-mini'})
)
.withVectorStore(
  new LibSQLVectorStore({
    embedder: new OpenAIEmbedder(),
  })
)
.withAuthProviders({
  google: new GoogleAuth(),
})
.on(
  'order/checkout/complete',
  async (event) => {
    // send a team slack message
  }
).init();

await migrateToLatest(app._.db, false);
await app._.vector_store?.createVectorIndex();

http
.createServer(app.handler)
.listen(
  8000,
  () => {
    app.print_banner('http://localhost:8000');
  }
); 

启动服务

运行上述代码后，您将启动一个本地服务器。终端将输出类似以下的信息，并显示访问地址：

• 后端 API: http://localhost:8000/api (查看 REST API 文档)
• 管理后台: http://localhost:8000/dashboard
• AI 客服聊天: http://localhost:8000/chat

核心功能概览

• AI 智能体: 内置 /chat 端点，支持连接主流 LLM（如 OpenAI），可处理购物车、结账咨询及商品相似性搜索。
• 多数据库支持: 示例中使用的是 LibSQL，您也可轻松切换至 MongoDB, PostgreSQL, MySQL, Neon, Turso 等。
• 支付集成: 已预配置 Stripe 和 PayPal，支持测试环境。
• 事件驱动: 通过 .on() 方法监听业务事件（如订单完成），轻松扩展业务逻辑（如发送 Slack 通知）。