This repository contains the TypeScript SDK for SpacetimeDB. The SDK allows to interact with the database server and is prepared to work with code generated from a SpacetimeDB backend code.
The SDK is an NPM package, thus you can use your package manager of choice like NPM or Yarn, for example:
npm install --save @clockworklabs/spacetimedb-sdk
You can use the package in the browser, using a bundler like webpack of vite, and in terminal applications
In order to connect to a database you have to create a new client:
import { SpacetimeDBClient } from "@clockworklabs/spacetimedb-sdk";
let client = new SpacetimeDBClient("spacetimedb.com/spacetimedb", "<db-name>");
If you would like to connect to the client you can call the below method. This also takes optional parameters to override the host or credentials:
client.connect();
If for some reason you need to disconnect the client:
client.disconnect();
This will connect to a database instance without a specified identity. If you want to persist an identity fetched on connection you can register an onConnect
callback, which will receive a new assigned identity as an argument:
client.onConnect((identity: string) => {
console.log(identity);
console.log(client.token);
});
You may also pass credentials as an optional third argument:
let credentials = { identity: "<identity>", token: "<token>" };
let client = new SpacetimeDBClient(
"spacetimedb.com/spacetimedb",
"<db-name>",
credentials
);
Typically, you will use the SDK with types generated from a backend DB service. For example, given a component named Player
you can subscribe to player updates by registering the component:
client.registerComponent(Player, "Player");
Then you will be able to register callbacks on insert and delete events, for example:
Player.onInsert((newPlayer: Player) => {
console.log(newPlayer);
});
Given a reducer called CreatePlayer
you can call it using a call method:
CreatePlayer.call("Nickname");