SpacetimeDB SDK

⚠️ Warning: As of version 1.4.0, this NPM package has MOVED to https://www.npmjs.com/package/spacetimedb. If you are on v1.3.2 and would like to upgrade, switch your package to spacetimedb. This package has been marked DEPRECATED to avoid confusion.

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 vite/parcel/rsbuild, in server-side applications like NodeJS, Deno, Bun and in Cloudflare Workers.

NOTE: For usage in NodeJS 18-21, you need to install the undici package as a peer dependency: npm install @clockworklabs/spacetimedb-sdk 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 for some reason you need to disconnect the client:

connection.disconnect();

Typically, you will use the SDK with types generated from a backend DB service. 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();

Developer notes

To run the tests, do:

pnpm compile && pnpm test