Spree TypeScript 包生态解析从 Store SDK 到 Admin Dashboard 的 monorepo 架构与实战指南【免费下载链接】spreeOpen Source eCommerce Platform for B2B, Marketplace, and Enterprise. REST API, TypeScript SDK, and production-ready Next.js storefront. Self-host it. Own your stack. No vendor lock-in. Zero platform fees.项目地址: https://gitcode.com/GitHub_Trending/sp/spree导读本文聚焦 Spree 开源电商平台 monorepo 中的 TypeScript 侧全景位于仓库 packages 目录下的 SDK、React 管理后台 SPA、CLI、项目脚手架与文档包是如何在pnpm workspaces Turbo的编排下协同工作的。读完本文你将掌握每个 npm 包的角色定位、稳定程度与适用场景理解spree/sdk/spree/admin-sdk的认证模式与请求层实现学会利用spree/dashboard-core的defineDashboardPlugin扩展 API 开发管理后台插件并能在仓库内直接跑通pnpm install / build / test / lint等 monorepo 工作流。一、monorepo 概况一套工具链贯穿所有 TypeScript 包packages/README.md明确指出packages 目录承载了 Spree 仓库的 TypeScript 侧全部内容SDK、React 管理后台 SPA、CLI、项目脚手架以及文档打包产物。整个目录统一由以下工具链管理关注点工具说明依赖管理pnpm workspaces所有包共享同一套 workspace 依赖拓扑构建编排Turbo带缓存的并行构建、测试、lint 调度打包器tsup管理后台 SPA 用ViteSDK 等库打包为 ESM/CJS 双格式测试Vitest后台另有 Playwright e2e单元测试与集成测试代码风格Biomelint format autofix版本发布Changesets按包独立管理版本与 changelog在仓库根目录的 package.json 中可以看到这套编排的直接证据preinstall脚本执行npx only-allow pnpm强制统一包管理器根脚本build、test、lint、typecheck全部通过turbo转发到各 workspace 包并且根目录声明了packageManager: pnpm11.1.1与engines: { node: 22 }。关于 monorepo 层面的类型生成管线从 Rails Alba 序列化器生成 TypeScript 类型与 Zod schema、代码风格与测试约定packages/README.md指引读者查阅根目录的 CLAUDE.md后端 Ruby 侧约定则在 spree 目录。二、状态图例如何判断一个包能否用于生产Spree 用统一的四级状态标注每个包的成熟度这决定了你在什么场景下可以依赖它们Badge含义Stable已发布到 npm遵循 semver可安全用于生产环境。Developer Preview已发布到 npm但 API 可能在 minor 版本之间发生变化使用时必须锁定精确版本。In Development为即将发布的 Spree 版本积极开发中尚未发布或仅以nextdist-tag 发布。Internal仅存在于 workspace 内部private: true不会发布到 npm。这套图例是理解下面包清单的关键Stable包可以放心接入生产项目Developer Preview包如spree/admin-sdk功能已可用但 API 未冻结需盯紧 changelogIn Development包如整个 dashboard 三件套随 Spree 6.0 一起交付目前仅在 workspace 内私有。三、包清单总览packages/README.md用一张表格给出了全部 9 个包其中 dashboard 三件套 sdk-core 尚未发布的身份与定位这里完整呈现包目录npm 名称状态说明sdkspree/sdkStable(1.x)面向顾客侧Store API v3的 TypeScript 客户端。admin-sdkspree/admin-sdkDeveloper Preview(0.x)面向Admin API v3Spree 5.5的 TypeScript 客户端以nextdist-tag 发布。dashboardspree/dashboard尚未发布In DevelopmentSpree 6.0 的 React SPA 管理后台将取代遗留的 Railsspree/adminengine。当前在 workspace 内私有就绪后发布。dashboard-uispree/dashboard-ui尚未发布In Development后台设计系统——shadcn 原语、headless 组合组件、设计 token。仅源码分发供spree/dashboard及下游插件作者消费。dashboard-corespree/dashboard-core尚未发布In Development后台框架——注册表table、nav、slot、settings-nav、providers、通用基础设施 hooks、defineDashboardPlugin。即扩展 API 面。sdk-core—Internal两个 SDK 共享的 HTTP/重试/错误处理层不发布。clispree/cliStable(2.x)基于 Docker 的 CLI管理由create-spree-app搭建的 Spree 项目。create-spree-appcreate-spree-appStable(1.x)一次性脚手架npx create-spree-app my-store搭建后端Docker 可选 Next.js storefront。docsspree/docsDeveloper Preview(0.x)Spree 开发者文档打包为纯 Markdown供 AI Agent 与本地工具读取。各包的package.json佐证了上述状态spree/sdk为1.2.1、spree/admin-sdk为0.8.1、spree/cli为2.4.9、create-spree-app为1.2.1、spree/dashboard为0.13.1且描述中明确标注 Developer Preview、spree/docs为0.1.0而 packages/sdk-core 无版本发布配置属于纯 workspace 内部包。四、spree/sdk与spree/admin-sdk两个面向不同 API 的 TypeScript 客户端4.1spree/sdk— Store API 客户端spree/sdk是面向顾客侧的 SDK为 storefrontNext.js 或其他以及任何需要读目录 写购物车/顾客/地址/结算的客户端提供能力。它支持两种认证模式publishable key访客/匿名会话JWT已登录顾客。其核心导入面在 packages/sdk/src/index.ts 中一览无余导出createClient与Client/ClientConfig类型主入口、StoreClient类供高级用法与子类化、全部资源类型同时从spree/sdk-core复导出RequestFn、RequestOptions、RetryConfig与SpreeError。也就是说SDK 的网络骨架完全建立在 sdk-core 之上。从 packages/sdk/package.json 可以看到它提供了多个子路径导出满足不同使用场景.— 主入口createClient等./types— 单独的类型子路径./zod— 自动生成的 Zod schemas 子路径用于运行时校验 API 数据./webhooks— webhook 相关辅助事件签名校验等。./zod正是packages/README.md提到的类型生成管线的产物SDK 自带的 TypeScript 类型与 Zod schema 由 Rails 的 Alba 序列化器自动派生详见根文档 CLAUDE.md。包内scripts/generate-zod.ts见 package.json 的generate:zod脚本是这条管线的入口生成代码由tsup打包。4.2spree/admin-sdk— Admin API 客户端spree/admin-sdk是spree/sdk的后台镜像同样的模式由 sdk-core 提供请求基础设施但目标 API 是 Admin API认证方式扩展为secret API key服务端到服务端基于 scope 的授权JWT管理员用户基于 CanCanCan 的授权。它被spree/dashboardSPA 内部使用同时也面向集成方与后台工具开放。需要特别留意的是Admin API v3 随Spree 5.5引入而 SDK 目前处于 0.x 的Developer Previewnextdist-tag 发布在 1.0 之前 minor 版本之间可能发生破坏性变更——这正是状态图例中 pin exact versions 的最佳示例。从 packages/admin-sdk/package.json 可见其当前版本为0.8.1导出结构.与./types两个子路径与spree/sdk保持一致。4.3 实战要点接入两个 SDK 的常规路径详见各包内README.md# 顾客侧 Store API pnpm add spree/sdk # 后台 Admin API注意锁定精确版本 pnpm add spree/admin-sdknextimport { createClient } from spree/sdk const client createClient({ baseUrl: https://your-store.example.com/api/v3, publishableKey: spree_pk_..., // 或登录后传入 JWT })import { createAdminClient } from spree/admin-sdk const admin createAdminClient({ baseUrl: https://your-store.example.com/admin-api/v3, secretKey: spree_secret_..., // 服务端到服务端或管理员 JWT })两包均把typescript声明为可选 peer dependencyspree/sdk还将zod也声明为可选 peer见 packages/sdk/package.json使不需要类型与校验的用户可以不安装额外依赖。五、spree/sdk-core两个 SDK 共享的请求基础设施spree/sdk-core是Internal私有包它把所有网络层复杂性收拢在一处供两个 SDK 复用不面向外部直接使用。从 packages/sdk-core/src/index.ts 可见其公共面createRequestFn()/RequestFn/RequestConfig— 创建绑定到某个 API scopestore 或 admin的请求函数SpreeError— 结构化错误类型重试配置与指数退避逻辑transformListParams()— 将前端查询参数转换为 Ransack 查询参数格式Rails 侧的过滤/排序语法。5.1createRequestFn的底层行为深入 packages/sdk-core/src/request.ts可以清晰看到这套基础设施的完整实现细节这也是理解两个 SDK 行为的关键请求选项RequestOptions这些选项既可在客户端级配置也可在每次请求时覆盖选项默认值说明token无Bearer token用于已认证请求spreeToken无访客购物车/结算/订单访问令牌locale客户端默认翻译内容语言如en、fr映射为x-spree-locale头currency客户端默认价格币种如USD、EUR映射为x-spree-currency头country客户端默认市场解析用的国家 ISO 码如US、DE映射为x-spree-country头channel客户端默认渠道编码如pos、wholesale以X-Spree-Channel头选择请求作用域idempotencyKey自动生成变更请求安全重试的幂等键最长 255 字符映射为Idempotency-Key头headers无自定义头与内置头合并重试配置RetryConfig的默认值同样写在源码中参数默认值说明maxRetries2最大重试次数retryOnStatus[429, 500, 502, 503, 504]触发重试的 HTTP 状态码baseDelay300指数退避的基础延迟msmaxDelay10000最大延迟上限msretryOnNetworkErrortrue网络错误是否重试源码中值得注意的几个工程决策非幂等请求只重试 429。shouldRetryOnStatus()规定只有GET/HEAD或携带幂等键的请求才按retryOnStatus全量重试否则仅对 429限流重试避免重复提交订单这类危险操作。幂等键自动生成。对变更请求非GET/HEAD且启用了重试时generateIdempotencyKey()会生成spree-sdk-retry-uuid形式的键并自动放入请求头用户提供的键优先。指数退避 抖动。calculateDelay()计算baseDelay * 2^attempt并叠加随机抖动jitter后与maxDelay取小若服务端返回Retry-After头则优先遵循该头同样受maxDelay上限约束。响应语义区分204 无内容直接返回undefined202 Accepted 根据Content-Type决定是否解析 JSON。错误规范化API 返回结构化错误时抛出SpreeError携带code、status、details代理页面错误与空响应体则统一包装为http_error防止把 HTTP 失败误判为网络错误而重试。sdk-core的测试覆盖了这些行为见 packages/sdk-core/tests是理解重试与错误语义的绝佳参考。六、管理后台三件套spree/dashboard-uispree/dashboard-corespree/dashboardSpree 6.0 的管理后台由三个包分工协作构成这是packages/README.md着墨最多、也最值得深入的部分。6.1 三层职责划分spree/dashboard-ui— 设计系统层。提供 shadcn 原语 headless 组合组件PageHeader、ResourceTable、AppSidebar等 设计 token。核心约束是Headless 规则组件只通过 props 接收数据绝不直接 import providers 或 hooks。它是 source-only 包由消费方Vite/Tailwind 应用编译因此不只限于spree/dashboard可以嵌入任何 React 应用。spree/dashboard-core— 框架层。提供四大注册表table、nav、slot、settings-nav、四大 providersauth、permission、store、theme、通用基础设施 hooksuse-auth、use-permissions、use-resource-mutation、use-direct-upload、use-global-search等、admin SDK 客户端单例以及defineDashboardPlugin扩展门面。插件作者要 import 的就是这个包用来注册导航、插槽、表格列与路由。spree/dashboard— 可部署的 SPA 壳。提供路由、资源 hooksuse-orders、use-products、use-customers等、Zod schemas、多语言文案与应用外壳组合另外两个包。技术栈为 Vite TanStack Router文件路由 TanStack Query React Hook Form Tailwind这从 packages/dashboard/package.json 的依赖清单可以得到印证。插件作者的依赖方式安装spree/dashboard-uispree/dashboard-core作为 peer dependencies卖家面板seller panels、白标后台及其他自定义变体则复用同样的包配合自己的路由/外壳进行组合。三个包当前都在 workspace 内私有随 Spree 6.0 一起发布。完整的架构设计、扩展点表格注册表、导航注册表、组件注入、包边界规则与分阶段迁移方案记录在 docs/plans/6.0-admin-spa.mdSPA 的本地开发环境搭建见 packages/dashboard/README.md。6.2defineDashboardPlugin插件扩展的单一入口packages/README.md指出 dashboard-core 是插件作者 import 的扩展 API 面。它的具体形态在 packages/dashboard-core/src/plugin.ts 中完整定义。插件入口模块在 import 时调用一次defineDashboardPlugin({...})后台应用在首次渲染前的 bootstrap 阶段 import 插件入口所有注册表基于useSyncExternalStore因此应用挂载后的晚注册依然会触发消费者重新渲染。插件配置DashboardPluginConfig支持以下扩展维度配置键作用nav侧边栏条目数组形式追加对象形式可add/remove/update改position、label、subject/addChildren在既有顶级菜单下嵌套子项settingsNavGroups/settingsNav设置子壳的分组与条目同样支持增删改slots按插槽名扩展组件每个条目id唯一如product.form_sidebartables按表格键做列变更add/remove/updateroutes自定义路由挂在/$storeId/之下路径为相对形式如/brands、/brands/$brandId由 dashboard 的 catch-all 路由分发formFields在既有资源表单如product上扩展字段经from从资源水合、随表单自身 Save 持久化customFieldComponents为特定自定义字段定义namespace.key指定输入组件替换默认 widgetlocales插件自己的文案按语言标签提供合并进基础命名空间不会覆盖后台自身文案defineDashboardPlugin的注册实现有几个值得借鉴的工程细节注册顺序上先add再addChildren允许插件先建父菜单再挂子项所有注册错误被收集后一次性抛出AggregateError而不是逐个报错方便插件作者在一次 reload 中看到全部冲突重复的 key/id 会直接抛错绝不静默双重注册。一个完整的插件示例摘自 plugin.ts 头部注释可直接作为插件骨架import { defineDashboardPlugin } from spree/dashboard-core/plugin import { Card } from spree/dashboard-ui function WishlistCount({ product }: { product: { wishlist_count: number } }) { return CardWishlists: {product.wishlist_count}/Card } defineDashboardPlugin({ nav: [ { key: wishlists, label: Wishlists, path: /wishlists, position: 50 }, ], slots: { product.form_sidebar: [ { id: wishlist-count, component: WishlistCount, position: 50 }, ], }, tables: { products: { add: [{ key: wishlist_count, label: Wishlists, sortable: true }] }, }, settingsNav: [ { key: wishlist-settings, label: Wishlists, path: /wishlists, group: integrations }, ], })此外dashboard-core 的 barrel 入口 packages/dashboard-core/src/index.ts 展示了它作为框架 组件 hooks 大集合的全貌除注册表与 providers 外还导出adminClient单例Vite 感知构建时读取VITE_SPREE_API_URL、can权限组件、resource-table、import-wizard-dialog等大量可复用组件以及filters-to-ransack、form-errors、query-keys等基础设施库。6.3 与遗留后台的关系spree/dashboard将取代遗留的 Railsspree/adminengine目前仍在 spree 目录下的 Rails 组件中。从 packages/dashboard/package.json 可确认其技术栈与发布形态source-only包通过spree/dashboard/vite子路径导出 Vite 插件供宿主编译依赖spree/admin-sdk、spree/dashboard-core、spree/dashboard-ui均为workspace:^测试体系包含 Vitest 单元测试与 Playwright e2eplaywright.config.ts、e2e/目录。七、spree/cli基于 Docker 的项目管理 CLIspree/cliStable 2.x专为create-spree-app搭建的项目提供 Docker 化运维命令新项目会自动捆绑它。典型能力包括启动/停止服务、运行迁移、打开 Rails console、加载示例数据等。根目录 package.json 中对应的脚本佐证了它的使用方式进入server/后调用spree console # 打开 Rails console spree logs # 查看服务日志 spree rails db:seed # 执行数据库种子数据 spree task load_sample_data # 加载示例数据CLI 依赖 packages/cli/package.json 中可见commander负责参数解析clack/prompts提供交互式提示execa执行子进程即 Docker 命令console-table-printer输出表格化结果构建时node scripts/bundle-spec.mjs会生成 OpenAPI spec 相关产物。八、create-spree-app新项目的推荐入口create-spree-appStable 1.x是一次性脚手架官方推荐的新项目入口。它的职责是克隆spree/spree-starter模板仓库 → 配置 Docker Compose → 可选添加 Next.js storefront → 执行首次设置从而取代了仓库遗留的server/目录工作流。仓库根目录 package.json 中的server:create脚本保留了这一历史路径的直接证据克隆spree-starter的6-0-dev分支到server/。典型用法npx create-spree-app my-store生成的项目中会附带spree/cli之后即可用spree命令完成日常运维。注意脚手架本身要求 Node 20见 packages/create-spree-app/package.json且与 CLI 共用clack/prompts、commander、execa等依赖另加get-port用于探测空闲端口。九、spree/docs为 AI Agent 与本地工具打包的文档spree/docsDeveloper Preview 0.x把 Spree 开发者文档核心概念、定制化、API 参考、集成指南打包成纯 Markdown使 AI Agent 与离线工具可以直接从node_modules/spree/docs/dist/读取。其构建输入就是仓库根部的 docs 目录。从 packages/docs/package.json 可见它的打包范围files字段只包含dist/**/*.md与dist/**/*.yaml即文档正文与 API 规范文件由node scripts/build.js从docs/树拷贝构建许可证为 CC-BY-4.0与源码包的 MIT 区分开。这一设计让 Agent 无需克隆整个仓库即可获得权威的本地文档源。十、在 monorepo 中开发命令速查packages/README.md给出了从仓库根目录出发的完整工作流命令这里原样继承并补充说明pnpm install # 安装 workspace 依赖 pnpm build # Turbo 缓存构建所有包 pnpm test # 运行全部包测试 pnpm typecheck # 全包 TypeScript 类型检查 pnpm lint # Biome lint pnpm lint:fix # Biome lint 自动修复 pnpm format # Biome format-write各包内还有更细粒度的命令如dev监听模式、test:watch、test:e2e等详见每个包自己的README.md。版本变更则通过Changesets管理变更集文件放在对应包的.changeset/目录根目录提供pnpm changeset、pnpm version:preview发布预览时忽略spree/sdk等脚本见根 package.json。结语通过packages/README.md这张总地图可以清晰地看到 Spree TypeScript 侧的完整版图spree/sdk与spree/admin-sdk是两个面向不同 API 的客户端共享spree/sdk-core这一经过工程打磨的请求层dashboard 三件套以 设计系统 / 框架 / SPA 壳 的分层配合defineDashboardPlugin这一强类型的扩展入口为 Spree 6.0 的后台插件生态提供了坚实基础而spree/cli、create-spree-app与spree/docs则分别解决了项目运维、初始化与文档可及性问题。在动手之前请务必对照状态图例确认所用包的成熟度——Stable 包可直接上生产Developer Preview 包需锁定版本In Development 与 Internal 包则建议只在同一 workspace 内使用。【免费下载链接】spreeOpen Source eCommerce Platform for B2B, Marketplace, and Enterprise. REST API, TypeScript SDK, and production-ready Next.js storefront. Self-host it. Own your stack. No vendor lock-in. Zero platform fees.项目地址: https://gitcode.com/GitHub_Trending/sp/spree创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考