Skip to main content
Version: 2.0.0

Node.js Quickstart

Get a SpacetimeDB Node.js app running in under 5 minutes.

Prerequisites​

Create your project

Run the spacetime dev command to create a new project with a SpacetimeDB module and Node.js client.

This starts the local SpacetimeDB server, publishes your module, generates TypeScript bindings, and runs the Node.js client.

spacetime dev --template nodejs-ts
Explore the project structure

Your project contains both server and client code.

Edit spacetimedb/src/index.ts to add tables and reducers. Edit src/main.ts to build your Node.js client.

my-spacetime-app/
├── spacetimedb/          # Your SpacetimeDB module
│   └── src/
│       └── index.ts      # Server-side logic
├── src/
│   ├── main.ts           # Node.js client script
│   └── module_bindings/  # Auto-generated types
└── package.json
Understand tables and reducers

Open spacetimedb/src/index.ts to see the module code. The template includes a person table and two reducers: add to insert a person, and sayHello to greet everyone.

Tables store your data. Reducers are functions that modify data — they're the only way to write to the database.

import { schema, table, t } from 'spacetimedb/server';

const spacetimedb = schema({
  person: table(
    { public: true },
    {
      name: t.string(),
    }
  ),
});
export default spacetimedb;

export const add = spacetimedb.reducer(
  { name: t.string() },
  (ctx, { name }) => {
    ctx.db.person.insert({ name });
  }
);

export const sayHello = spacetimedb.reducer(ctx => {
  for (const person of ctx.db.person.iter()) {
    console.info(`Hello, ${person.name}!`);
  }
  console.info('Hello, World!');
});
Run the client

spacetime dev starts both the server and the Node.js client. The client connects to SpacetimeDB, subscribes to tables, and displays people as they are added or removed. Press Ctrl+C to exit.

spacetime dev --template nodejs-ts
Call reducers from the SpacetimeDB CLI

Use the SpacetimeDB CLI to add people and invoke reducers. Changes appear in your Node.js client in real time.

# Add a person
spacetime call add Alice
spacetime call add Bob

# Greet everyone (check server logs)

spacetime call say_hello

# Query the database

spacetime sql "SELECT * FROM person"
Understand the client code

Open src/main.ts to see the Node.js client. It uses DbConnection.builder() to connect to SpacetimeDB, subscribes to tables, and registers callbacks for insert/delete events. Unlike browser apps, Node.js stores the authentication token in a file instead of localStorage. Enable withAutomaticReconnect() to recover after connection loss. onConnect fires once per connection object, so subscriptions and row callbacks can be initialized there or once after build(). Successful automatic reconnects fire onAutomaticReconnect instead, before subscriptions are replayed.

import { DbConnection } from './module_bindings/index.js';

const conn = DbConnection.builder()
  .withUri(HOST)
  .withDatabaseName(DB_NAME)
  .withToken(loadToken())
  .withAutomaticReconnect()
  .onConnect((_conn, identity, token) => {
    console.log('Connected! Identity:', identity.toHexString());
    saveToken(token);
  })
  .onAutomaticReconnect((_conn, identity, token) => {
    console.log('Reconnected! Identity:', identity.toHexString());
    saveToken(token);
  })
  .build();

conn.subscriptionBuilder()
  .onApplied(ctx => {
    console.log('Current people:', [...ctx.db.person.iter()].length);
  })
  .subscribeToAllTables();

conn.db.person.onInsert((_ctx, person) => {
  console.log(`[Added] ${person.name}`);
});
More CLI examples

The SpacetimeDB CLI can call reducers and query your data. Changes appear in your Node.js client in real time.

# Call the add reducer to insert a person
spacetime call add Charlie

# Query the person table

spacetime sql "SELECT * FROM person"
name

---

"Alice"
"Bob"
"Charlie"

# Call sayHello to greet everyone

spacetime call say_hello

# View the module logs

spacetime logs
2025-01-13T12:00:00.000000Z INFO: Hello, Alice!
2025-01-13T12:00:00.000000Z INFO: Hello, Bob!
2025-01-13T12:00:00.000000Z INFO: Hello, Charlie!
2025-01-13T12:00:00.000000Z INFO: Hello, World!
Node.js considerations

WebSocket support: Node.js 22+ has native WebSocket support. For Node.js 18-21, the SDK automatically uses the undici package (included in devDependencies).

Environment variables: Configure the connection using SPACETIMEDB_HOST and SPACETIMEDB_DB_NAME environment variables.

Exiting: Press Ctrl+C to stop the client.

# Configure via environment variables
SPACETIMEDB_HOST=ws://localhost:3000 \
SPACETIMEDB_DB_NAME=my-app \
npm run start

# Or use a .env file with dotenv

Next steps​