@clockworklabs/spacetimedb-sdk v0.9.0

SpacetimeDB SDK

Overview

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.

Installation

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

Usage

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");