SpacetimeDB TypeScript SDK 完全指南：从模块绑定生成到 React / SolidJS 响应式前端

SpacetimeDB TypeScript SDK 完全指南从模块绑定生成到 React / SolidJS 响应式前端【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB本文以 SpacetimeDB 仓库中的 TypeScript SDKcrates/bindings-typescript/README.md为核心系统讲解如何安装spacetimedbNPM 包、通过DbConnection.builder()连接数据库、订阅表与调用 reducer以及如何在 React 和 SolidJS 中利用官方 Hooks/Primitives 构建与 StrictMode 兼容的响应式前端。读完本文你将掌握从连接建立、订阅管理到框架集成的一整套实战技能并能对照仓库源码理解其底层实现。一、SDK 定位模块库 客户端 SDKspacetimedb这个 NPM 包源码位于 crates/bindings-typescript同时承担两项职责SpacetimeDB 模块Module库服务端模块的 TypeScript 绑定用于编写服务端逻辑TypeScript SDK供客户端与 SpacetimeDB 数据库服务器交互并应用来自你服务端模块的类型信息——即你在 Rust/TypeScript 模块中定义的表、reducer、procedure生成后的绑定会直接体现在DbConnection的类型上实现端到端类型安全。从 crates/bindings-typescript/package.json 可以看到包名为spacetimedb采用 ESM 优先的多入口导出exports字段核心入口之外还暴露了./react、./solid、./vue、./svelte、./tanstack、./angular、./server、./sdk等子路径分别对应不同框架与场景的绑定。二、安装与运行环境SDK 是标准 NPM 包可以使用任何包管理器安装npm add spacetimedb或者使用 Yarnyarn add spacetimedb官方 README 明确说明该包可在以下环境使用浏览器配合 vite / parcel / rsbuild 等打包器服务端应用NodeJS、Deno、Bun、NextJS、RemixCloudflare Workers。NodeJS 版本注意事项在 NodeJS 18–21 上使用需要额外安装undici作为 peer dependencynpm add spacetimedb undiciNode 22 及以上版本开箱即用。仓库的package.json将undici声明为 optional peerDependency版本^6.19.2且 peerDependencies 中react^18 || ^19、solid-js^1.6.0、vue、svelte、angular/core、tanstack/react-query均为 optional也就是说你可以按需只安装自己用的框架绑定。三、连接数据库DbConnection 构建器要连接数据库首先需要为你的数据库生成模块绑定module_bindings。生成后绑定文件会导出DbConnection、tables、reducers、procedures等对象。连接采用链式构建器模式import { DbConnection, tables } from ./module_bindings; const connection DbConnection.builder() .withUri(ws://localhost:3000) .withDatabaseName(MODULE_NAME) .onDisconnect(() { console.log(disconnected); }) .onConnectError(() { console.log(client_error); }) .onConnect((connection, identity, _token) { console.log( Connected to SpacetimeDB with identity:, identity.toHexString() ); connection.subscriptionBuilder().subscribe(tables.player); }) .withToken(TOKEN) .build();3.1 构建器方法解析对照源码 db_connection_builder.ts每个方法的语义如下方法参数说明withUri(uri)string \| URL设置要连接的 SpacetimeDB 服务器 URI如ws://localhost:3000withDatabaseName(name)string设置要连接的远程数据库名称或地址。build()时会校验 URI 与数据库名缺一不可否则抛错withToken(token?)string \| undefined认证凭据。可省略匿名连接成功后onConnect会收到服务器生成的新凭据保存下来即可用于后续登录withLightMode(boolean)boolean开启轻量模式减少网络传输的数据量SDK 默认falsewithCompression(c)gzip \| brotli \| none连接压缩算法默认gzip。选择brotli时构建器会先探测运行时的DecompressionStream支持情况不支持则抛出TypeErrorwithConfirmedReads(boolean)boolean开启确认读服务器只在事务被确认持久化后下发查询结果。注意这会增加 reducer 调用与订阅更新到达客户端之间的延迟不调用则不向服务器发送偏好由服务器选择默认策略withWSFn(fn)WebSocketFactory自定义 WebSocket 工厂用于替换默认的 WebSocket 创建逻辑SDK 默认使用WebsocketDecompressAdapter.openWebSocketonConnect(cb)(connection, identity, token) void认证成功后回调。匿名连接时identity/token为新生成的一套凭据可保存复用onConnectError(cb)(ctx, error) void连接出错时回调onDisconnect(cb)(ctx, error?) void断线时回调仅在build()成功且onConnect已触发之后断开才会触发同一 builder 上多次注册会抛错build()—用当前参数构造DbConnection并开始连接关于onConnect的凭据语义源码注释说得非常清楚如果连接时提供了凭据回调收到的与传入一致如果是匿名连接数据库会生成新的 identity/token 来标识该用户回调中拿到的凭据可以保存下来在未来的连接中用来认证同一用户。3.2 断开连接需要主动断开时直接调用connection.disconnect();3.3 底层实现要点从源码结构看build()最终通过构造器函数dbConnectionCtor创建DbConnectionImpl实例并把uri、nameOrAddress、identity、token、emitter、compression、lightMode、confirmedReads、createWSFn、remoteModule等配置整体传入见 db_connection_builder.ts。连接管理、缓存、事件分发分别封装在src/sdk/下的connection_manager.ts、table_cache.ts、event_emitter.ts、websocket_decompress_adapter.ts等模块中连接后收到的SubscriptionApplied、TransactionUpdate等协议消息定义在由 Rust 的client-api-messages生成的 src/sdk/client_api 目录。四、订阅表与调用 reducer / procedure4.1 订阅表更新SDK 带类型信息例如服务端有名为Player的表客户端可以这样订阅插入事件connection.db.player.onInsert((ctx, player) { console.log(player); });connection.db下暴露了与模块 schema 一一对应的表对象可注册onInsert、onUpdate、onDelete等回调回调的第二个参数即为强类型的行对象。4.2 调用 reducer给定名为CreatePlayer的 reducer调用方式为connection.reducers.createPlayer();reducers同样由绑定生成方法签名与模块中的 reducer 参数一一对应编译期即可获得参数类型检查。4.3 订阅构建器进阶SQL、回调与退订除了用tables.player这类类型化查询订阅subscriptionBuilder()还接受 SQL 字符串和查询构建器函数。对照 subscription_builder_impl.ts其能力包括subscribe(query)订阅单个查询接受 SQL 字符串、类型化查询RowTypedQuery或一个接收tables命名空间构建器、返回一个/多个查询的函数返回SubscriptionHandleImpl可调用unsubscribe()/unsubscribeThen(cb)退订并可通过isActive()/isEnded()查询订阅状态onApplied(cb)订阅成功应用收到SubscriptionApplied消息时回调此时EventContext中包含新订阅加入客户端缓存的所有行onError(cb)订阅添加失败或意外被移除时回调subscribeToAllTables()一次性订阅所有表的所有行。源码注释明确提醒这只是一个客户端内存与网络带宽不成问题时的便捷方法资源受限的应用应使用更精确的查询。且subscribeToAllTables与subscribe不能在同一个连接上混用否则可能导致订阅被丢弃、客户端缓存损坏甚至抛错。const subscription connection.subscriptionBuilder() .onApplied(() { console.log(SDK client cache initialized.); }) .subscribe(SELECT * FROM User); subscription.unsubscribe();底层实现中subscribe会把每个类型化查询通过toSql()转换为 SQL 字符串见 src/lib/query.ts随后SubscriptionHandleImpl通过db.registerSubscription(...)注册订阅并拿到querySetId用于后续退订。五、React 集成StrictMode 兼容的 HooksSDK 在spacetimedb/react子路径下提供了 React Hooks官方明确说明其与 React StrictMode 完全兼容能够正确处理双挂载行为只会创建一条 WebSocket 连接。5.1 挂载 Provider在组件树顶层添加SpacetimeDBProvider传入构建器注意不要调用build()Provider 内部会负责连接管理const connectionBuilder DbConnection.builder() .withUri(ws://localhost:3000) .withDatabaseName(MODULE_NAME) .withLightMode(true) .onDisconnect(() { console.log(disconnected); }) .onConnectError(() { console.log(client_error); }) .onConnect((conn, identity, _token) { console.log( Connected to SpacetimeDB with identity:, identity.toHexString() ); conn.subscriptionBuilder().subscribe(tables.player); }) .withToken(TOKEN); ReactDOM.createRoot(document.getElementById(root)!).render( React.StrictMode SpacetimeDBProvider connectionBuilder{connectionBuilder} App / /SpacetimeDBProvider /React.StrictMode );5.2 在组件中使用 Hooksfunction App() { const conn useSpacetimeDBDbConnection(); const { rows: messages } useTableDbConnection, Message(message); // ... }useSpacetimeDBDbConnection()访问连接状态identity、token、连接错误等useTableDbConnection, TableType(table_name)订阅某张表返回{ rows }useReducer、useProcedure调用 reducer 与 procedure。React 绑定的源码位于 src/reactSpacetimeDBProvider的实现SpacetimeDBProvider.ts有三个关键设计以uri moduleName计算连接键ConnectionManager.getKey(uri, moduleName)保证同一数据库复用同一条连接通过React.useSyncExternalStore订阅ConnectionManager的外部状态StrictMode 下即使组件双挂载连接也只是被retain/release引用计数而不会重复创建 WebSocketgetServerSnapshot返回 fallback 状态避免服务端渲染SSR时的水合不一致。六、SolidJS 集成细粒度响应式 PrimitivesSDK 在spacetimedb/solid子路径下提供 SolidJS primitives利用 Solid 的细粒度响应式系统createSignal、createStore、createMemo、createComputed获得最优渲染性能响应式更新只作用于实际变化的数据。6.1 挂载 Providerimport { SpacetimeDBProvider } from spacetimedb/solid; import { DbConnection, tables } from ./module_bindings; const connectionBuilder DbConnection.builder() .withUri(ws://localhost:3000) .withDatabaseName(MODULE_NAME) .withLightMode(true) .onDisconnect(() { console.log(disconnected); }) .onConnectError(() { console.log(client_error); }) .onConnect((conn, identity, _token) { console.log( Connected to SpacetimeDB with identity:, identity.toHexString() ); conn.subscriptionBuilder().subscribe(tables.player); }) .withToken(TOKEN); render( () ( SpacetimeDBProvider connectionBuilder{connectionBuilder} App / /SpacetimeDBProvider ), document.getElementById(root)! );6.2 在组件中使用 Primitivesimport { useSpacetimeDB, useTable, useReducer, useProcedure, } from spacetimedb/solid; function App() { // 访问连接状态identity、token、连接错误等 const conn useSpacetimeDB(); // 订阅一张表——返回响应式 rows store 与 isReady accessor const [rows, isReady] useTable(() tables.message); // 订阅过滤视图 const [onlineUsers, onlineReady] useTable( () tables.user.where(r r.online.eq(true)), { onInsert: row console.log(User came online:, row), onDelete: row console.log(User went offline:, row), } ); // 调用 reducer——连接就绪前的调用会被排队 const sendMessage useReducer(reducers.sendMessage); // 调用 procedure——连接就绪前的调用会被排队 const getResult useProcedure(procedures.getSomeResult); return ( div Show when{isReady()} fallback{pLoading.../p} p{rows.length} messages/p For each{rows}{row div{row.text}/div}/For /Show button onClick{() sendMessage(hello)}Send/button /div ); }6.3 与 React API 的关键差异官方 README 明确列出了以下几点useTable接收一个getter 函数() QueryTableDef而非普通值使查询本身具备响应性signal 变化时查询会随之更新useTable返回[rows, isReady]其中rows是 Solid 响应式 storeisReady是访问器函数() booleanenabled回调选项是 getter() boolean而非普通布尔值允许它依赖响应式状态useReducer和useProcedure会把连接就绪前的调用排队待连接建立后统一冲刷执行。Solid 绑定源码位于 src/solid与 React 版目录结构对称SpacetimeDBProvider.ts、useSpacetimeDB.ts、useTable.ts、useReducer.ts、useProcedure.ts。七、多框架支持一览除了 React 与 SolidJSSDK 的package.json还声明了 Vue、Svelte、TanStack Query、Angular 的框架绑定子路径./vue、./svelte、./tanstack、./angular对应源码目录 src/vue、src/svelte、src/tanstack、src/angular相关框架均以 optional peerDependency 形式声明按需安装。仓库中 templates 目录提供了多个框架的完整可运行示例如chat-react-ts、react-ts、solid-ts、vue-ts、svelte-ts、tanstack-ts等以及测试应用 test-react-router-app 和 test-solid-router可作为集成参考。八、开发者指南测试与绑定再生成仓库为维护者提供了可复现的开发流程详见 DEVELOP.md运行测试pnpm build pnpm testpackage.json中build由tsup打包 JS、tsc生成类型声明test使用 Vitestvitest run另有test:typecheck进行类型检查测试。再生成绑定src/sdk/client_api由 Rust 的client-api-messagescrate 生成src/lib/autogen由regen-typescript-moduledef程序从ModuleDef定义生成。当这两者发生变更时运行pnpm generate即可一次性重新生成 client API、模块定义、测试应用与各示例工程的绑定。发布升级版本号后执行npm publishprepublishOnly脚本会自动执行构建、测试与体积检查。此外package.json中的size-limit配置对核心产物与 React/SDK 的最小化产物设置了体积上限如 core ESM 最小化产物 brotli 约 30 kB 以内说明该 SDK 对包体积有明确的预算约束适合对首屏性能敏感的前端项目。九、小结本文围绕 crates/bindings-typescript/README.md 完整梳理了 SpacetimeDB TypeScript SDK 的使用路径安装与运行环境 →DbConnection.builder()连接配置URI、数据库名、token、轻量模式、压缩、确认读→ 表订阅与 reducer/procedure 调用 → ReactStrictMode 兼容与 SolidJS细粒度响应式框架集成 → 多框架绑定与开发者再生成流程。对照 crates/bindings-typescript/src 下的源码你可以进一步深入阅读db_connection_builder.ts、subscription_builder_impl.ts、connection_manager.ts与src/react、src/solid各实现验证文中每一处行为描述的底层依据。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考