John Detter
3c1c3415a2
# Description of Changes <!-- Please describe your change, mention any related tickets, and so on here. --> This bumps the Typescript SDK to 1.11.3. # API and ABI breaking changes <!-- If this is an API or ABI breaking change, please apply the corresponding GitHub label. --> None # Expected complexity level and risk 1 <!-- How complicated do you think these changes are? Grade on a scale from 1 to 5, where 1 is a trivial change, and 5 is a deep-reaching and complex change. This complexity rating applies not only to the complexity apparent in the diff, but also to its interactions with existing and future code. If you answered more than a 2, explain what is complex about the PR, and what other components it interacts with in potentially concerning ways. --> # Testing <!-- Describe any testing you've done, and any testing you'd like your reviewers to do, so that you're confident that all the changes work as expected! --> NA - this is just a version bump and the CI passes I will change the base to master once the `1.11.2` version bump merges. --------- Signed-off-by: John Detter <4099508+jdetter@users.noreply.github.com>
SpacetimeDB Module Library and SDK
Overview
This repository contains both the SpacetimeDB module library and the TypeScript SDK for SpacetimeDB. The SDK allows you to interact with the database server from a client and applies type information from your SpacetimeDB server module.
Installation
The SDK is an NPM package, thus you can use your package manager of choice like NPM or Yarn, for example:
npm add spacetimedb
You can use the package in the browser, using a bundler like vite/parcel/rsbuild, in server-side applications like NodeJS, Deno, Bun, NextJS, Remix, and in Cloudflare Workers.
NOTE: For usage in NodeJS 18-21, you need to install the
undicipackage as a peer dependency:npm add spacetimedb undici. Node 22 and later are supported out of the box.
Usage
In order to connect to a database you have to generate module bindings for your database.
import { DbConnection } from './module_bindings';
const connection = DbConnection.builder()
.withUri('ws://localhost:3000')
.withModuleName('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('SELECT * FROM player');
})
.withToken('TOKEN')
.build();
If you need to disconnect the client:
connection.disconnect();
Typically, you will use the SDK with types generated from SpacetimeDB module. For example, given a table named Player you can subscribe to player updates like this:
connection.db.player.onInsert((ctx, player) => {
console.log(player);
});
Given a reducer called CreatePlayer you can call it using a call method:
connection.reducers.createPlayer();
React Usage
This module also include React hooks to subscribe to tables under the spacetimedb/react subpath. In order to use SpacetimeDB React hooks in your project, first add a SpacetimeDBProvider at the top of your component hierarchy:
const connectionBuilder = DbConnection.builder()
.withUri('ws://localhost:3000')
.withModuleName('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('SELECT * FROM player');
})
.withToken('TOKEN');
ReactDOM.createRoot(document.getElementById('root')!).render(
<React.StrictMode>
<SpacetimeDBProvider connectionBuilder={connectionBuilder}>
<App />
</SpacetimeDBProvider>
</React.StrictMode>
);
One you add a SpacetimeDBProvider to your hierarchy, you can use SpacetimeDB React hooks in your render function:
function App() {
const conn = useSpacetimeDB<DbConnection>();
const { rows: messages } = useTable<DbConnection, Message>('message');
...
}
Developer notes
To run the tests, do:
pnpm build && pnpm test