Commit Graph

346 Commits

Author SHA1 Message Date
bradleyshep c14c8d15b0 TS quickstart template fixes (nextjs + nodejs) (#4380)
# Description of Changes

- Node.js: Use esbuild instead of tsx 
- Node.js: Remove interactive CLI since it doesn't work with `spacetime
dev`
- Next.js: Fix onError callback to use single argument (ctx) and use
ctx.event for the error.
- Next.js: Replace lint-disable comment with `_connection` for the
unused variable.
- Updated quickstart docs to use proper `withDatabaseName`

# API and ABI breaking changes

None.

# Expected complexity level and risk

**Complexity: 1–2.** Small tooling, type, and lint tweaks. Low risk.

# Testing

- [ ] Build affected templates (e.g. `pnpm build` in nextjs-ts).
- [ ] Lint passes.
2026-02-22 11:05:56 +00:00
Phoebe Goldman 2d4395c76d Docs: SpacetimeDB 2.0 migration guide (#4383)
# Description of Changes

Expanded and reorganized the 2.0 migration guide, and also deleted a
file that was in the wrong place. (The word "migration" is
overloaded...)

# API and ABI breaking changes

N/a

# Expected complexity level and risk

Like, 1 I guess, since this isn't code? But we should be careful to get
this right.

# Testing

- [x] Pasted all 2.0 Rust examples into a project based on the
`basic-rs` template and got 'em to build.
- This required filling in some code outside the examples (defining
`play_damage_animation`, binding `target` and `amount`), and changing
one table name that was used in two examples, but otherwise everything
is valid.
  - I didn't test the 1.0 examples.

---------

Co-authored-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: = <cloutiertyler@gmail.com>
2026-02-21 03:29:39 +00:00
Jeffrey Dallatezza bddfc19725 Add doc versioning (#4381)
# Description of Changes

This change cuts a version of the docs from 1.12.0
(e45cf891c2), and saves it under
`docs/versioned_docs/version-1.12.0`.

If you go to the docs page, it will redirect to the 1.12.0 docs, which
has a banner at the top for trying the prerelease docs:
<img width="1027" height="283" alt="Screenshot 2026-02-20 at 12 07
39 PM"
src="https://github.com/user-attachments/assets/8ff3d622-b693-469a-980a-01c34d0506b8"
/>

If you select the prelease docs, there is a warning banner at the top:
<img width="886" height="299" alt="Screenshot 2026-02-20 at 12 08 52 PM"
src="https://github.com/user-attachments/assets/5508a635-765e-40cc-ad2a-cbbed7f779dd"
/>


# Expected complexity level and risk

This only changes docs.

# Testing

I've testing by running this locally.
2026-02-20 22:41:39 +00:00
bradleyshep e256ceff33 Change deno quickstart to use package.json instead of deno.json (#4374)
# Description of Changes

Deno quickstart template now uses `package.json` instead of `deno.json`
so `spacetime dev` can run it. Added `templates/deno-ts/package.json`,
removed `deno.json`, and updated the Deno quickstart doc.

# API and ABI breaking changes

None.

# Expected complexity level and risk

**1** — Template and docs only.

# Testing

- [ ] `spacetime dev --template deno-ts` and confirm client runs.
- [ ] Spot-check updated Deno quickstart doc.
2026-02-20 19:05:59 +00:00
Piotr Sarnacki 19cc87ebfa Allow skipping DB if the config file is available (#4358)
# Description of Changes

This PR introduces a possibility to skip passing a DB name to various
commands if there is a config file with one database defined

# API and ABI breaking changes

This changes the behaviour of several CLI commands:

  1. call
  2. subscribe
  3. sql
  4. describe
  5. logs
  6. delete

# Expected complexity level and risk

4 - it's tricky to get all of the combinations of CLI arguments right

# Testing

I've tested the simplest cases manually.

---------

Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: = <cloutiertyler@gmail.com>
2026-02-20 17:48:54 +00:00
Shubham Mishra e2f8a60759 Case conversion (#4263)
# Description of Changes

Update the Default casing policy to `snake_case` for `RawModuleDefV10`.

Messy PR contains changes at different places, so that CI can pass:

Here are the main changes as follows:
- `bindings-macro` & `bindings` crate: `name` macro in Indexes for
canonical name and supply it to `RawModuleDefV10` via `ExplicitNames`.
- `bindings-typescript`: 
- Changes has been reviewed through this PR -
https://github.com/clockworklabs/SpacetimeDB/pull/4308.
   
- `binding-csharp`: a single line change to pass `sourceName` of index
instead of null.
- `codegen`:
  
- Changes has been merged from branch -
https://github.com/clockworklabs/SpacetimeDB/pull/4337.
  
- Except a fix in rust codegen to use canonical name in Query buillder
instead of accessor.
  
- `lib/db/raw_def`: Extends `RawDefModuleV10` structure to support case
conversion.
  
- `schema` crate:
- `validate/v9` - Nothing itself should change or changes in v9
validation logic but the file contains a `CoreValidator` which is shared
with `validate/v10`. No test have t be updated to `validate/v9` which
ensures we aren't regressing it.
- `validate/v10`: This is the main meat, look at the new tests added in
bottom to understand what it does.
     
   -  Rest of the files are either test updates or module bindings. 
     
    ## Testing:
1. Extensive unit tests have been added to verify generated `ModuleDef`
is correct.
2. I have done some e2e testing to verify rust codegen with rust and
typescript modules.
3. I would have like to do more testing for other codegens , I am
continue doing .

I have removed `sql.py` smoketest, as that seems to be already migated
in new framework and was headache to update.

## Expected complexity level and risk
4, It could have side-effect which aren't easily visible.


 
 
 
 
 
 -  -  -

---------

Signed-off-by: Shubham Mishra <shivam828787@gmail.com>
Co-authored-by: rekhoff <r.ekhoff@clockworklabs.io>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <bot@clockworklabs.com>
Co-authored-by: joshua-spacetime <josh@clockworklabs.io>
Co-authored-by: Noa <coolreader18@gmail.com>
Co-authored-by: = <cloutiertyler@gmail.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@clockworklabs.io>
Co-authored-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: Phoebe Goldman <phoebe@clockworklabs.io>
2026-02-20 10:44:29 +00:00
Tyler Cloutier b2bb2180c5 Fix spacetime dev watch filtering and improve quickstart copy-paste experience (#4317)
## Summary
- Fix `spacetime dev` failing on C# projects by watching the module
directory itself instead of hardcoded `spacetimedb_dir/src/` (which
doesn't exist for C# templates)
- Add layered file-watch filtering to avoid triggering rebuilds on build
artifacts:
1. Always-ignore dirs (`target/`, `bin/`, `obj/`, `node_modules/`, etc.)
  2. Always-watch exceptions (`.env.local`, `spacetime.*.local.json`)
  3. `.gitignore` rules from global, project, and module levels
- Suppress init's generic "Next steps" message when called from
`spacetime dev`, print a dev-appropriate `cd` hint instead when a new
project is created in a subdirectory
- Update 12 quickstart docs to tell users to open a new terminal and `cd
my-spacetime-app` before running CLI commands

## Test plan
- [x] `cargo build -p spacetimedb-cli` compiles successfully
- [ ] `spacetime dev --template basic-cs` no longer errors with "Input
watch path is neither a file nor a directory"
- [ ] Modifying a `.cs` file in `spacetimedb/` triggers a rebuild
- [ ] Build artifacts in `obj/`/`bin/` do not trigger rebuilds
- [ ] Rust projects (`spacetimedb/src/` exists) continue to work as
before
- [ ] `spacetime dev --template basic-cs` from a non-project directory
prints the "Tip: cd" hint, not the generic "Next steps"
- [ ] `spacetime init` standalone still prints "Next steps" as before

---------

Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
2026-02-19 23:12:34 +00:00
John Detter 27bb9f8edf Remove database names in quickstarts (#4354)
# Description of Changes

<!-- Please describe your change, mention any related tickets, and so on
here. -->

- For the quickstarts we don't want to pass a database name during
`spacetime dev --template ...`

# API and ABI breaking changes

<!-- If this is an API or ABI breaking change, please apply the
corresponding GitHub label. -->

None - this is just docs

# Expected complexity level and risk

None - this is just docs

<!--
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! -->

- [x] All quickstarts no longer pass a database name during `spacetime
dev --template ...`
2026-02-19 21:18:29 +00:00
doug ae8c9159b3 Add ConnectionManager for robust React lifecycle handling (#4028)
## Summary
- Add `ConnectionManager` singleton that uses reference counting and
deferred cleanup to handle React StrictMode's double-mount behavior
- Implement TanStack Query-style pattern: `retain()` / `release()`
instead of direct connect/disconnect
- Use `useSyncExternalStore` for tear-free state reads in React

## Changes
- **New:** `src/sdk/connection_manager.ts` - Core ConnectionManager
implementation
- **Modified:** `src/react/SpacetimeDBProvider.ts` - Now uses
ConnectionManager
- **Modified:** `src/react/connection_state.ts` - Simplified type,
imports from ConnectionManager
- **Modified:** `src/sdk/db_connection_builder.ts` - Added `getUri()`
and `getModuleName()` methods
- **Modified:** `src/sdk/db_connection_impl.ts` - Minor type updates for
ConnectionManager integration
- **New:** `tests/connection_manager.test.ts` - 33 unit tests
- **Docs:** Added React Integration section to TypeScript reference
- **Docs:** Added StrictMode compatibility note to README

## Test plan
- [x] `pnpm test` passes (104 tests)
- [x] `pnpm build` passes
- [x] Manual browser test with React StrictMode - single WebSocket
connection

---

## Motivation

### The Problem

React StrictMode double-mounts components in development to help catch
bugs:

1. Mount → creates WebSocket connection
2. Unmount → destroys WebSocket connection
3. Remount → creates **another** WebSocket connection

Without ConnectionManager, you get either:
- **Two connections** (if you don't clean up on unmount)
- **Broken connection** (if you clean up on unmount, the remount races
with cleanup)

### Why ConnectionManager? (vs alternatives)

| Alternative | Problem |
|-------------|---------|
| Don't clean up on unmount | Leaks connections, memory leaks, stale
subscriptions |
| Disable StrictMode | Hides real bugs, production still has edge cases
|
| Connection in module scope | React can't react to state changes, no
`useSyncExternalStore` |

**ConnectionManager approach** (TanStack Query pattern):
- Reference counting: multiple components share one connection
- Deferred cleanup: `setTimeout(0)` lets StrictMode remount cancel
cleanup
- External store: connection state lives outside React but syncs
properly

---

## Why Two `useSyncExternalStore` Usages?

The SDK now has two places using `useSyncExternalStore`. They solve
different problems:

| | `useTable` | `ConnectionManager` |
|---|---|---|
| **Subscribes to** | Table row changes | Connection state changes |
| **External store** | `DbConnection.db.tableName` callbacks |
`ConnectionManager` singleton |
| **Re-renders when** | Row inserted/deleted/updated | `isActive`,
`identity`, `error` change |
| **Manages lifecycle?** |  No - assumes connection exists |  Yes -
owns connect/disconnect |

### `useTable` assumes a connection exists

```tsx
// useTable.ts - subscribes to TABLE DATA
useEffect(() => {
  const connection = connectionState.getConnection()!;  // assumes this exists
  if (connectionState.isActive && connection) {
    const cancel = connection.subscriptionBuilder().subscribe(query);
    return () => cancel.unsubscribe();
  }
}, [...]);
```

### `ConnectionManager` manages WHEN the connection exists

```tsx
// OLD SpacetimeDBProvider - broken with StrictMode
useEffect(() => {
  const conn = builder.build();    // Creates WebSocket
  return () => conn.disconnect();  // Destroys WebSocket
}, [builder]);
// StrictMode: build → disconnect → build = TWO CONNECTIONS RACING

// NEW SpacetimeDBProvider - works with StrictMode  
useEffect(() => {
  ConnectionManager.retain(key, builder);   // refCount++, maybe create
  return () => ConnectionManager.release(key); // refCount--, deferred cleanup
}, [key, builder]);
// StrictMode: retain(1) → release(0, schedule) → retain(1, cancel) = ONE CONNECTION
```

### The Layered Architecture

```
ConnectionManager (lifecycle: retain/release, deferred cleanup)
    ↓
SpacetimeDBProvider (React context + useSyncExternalStore for connection state)
    ↓
useTable (useSyncExternalStore for table data)
```

- `useTable` syncs **data** from an existing connection
- `ConnectionManager` syncs **connection state** AND manages **when the
connection exists**

---------

Co-authored-by: Jeffrey Dallatezza <jeffreydallatezza@gmail.com>
2026-02-19 16:21:19 +00:00
joshua-spacetime 41cfbbc7e0 Update subscription and query builder docs (#4329)
# Description of Changes

This patch does the following:

- Adds api reference docs for the module-side query builder in the view
docs
- Merges the client sdk and subscription docs pages
- Keeps subscription and client overview docs high-level (moved all api
docs to the language reference docs)
- Replaces SQL examples in the docs with the query builder
- Replaces SQL subscriptions in the templates with the query builder

Note, the last commit in this patch set transitions the templates over
to use the query builder instead of SQL subscriptions. This will break
them temporarily until #4000 merges.

Also note, a lot of this was AI assisted. It can still be improved upon,
but it's in a better state than it was.

# API and ABI breaking changes

N/A

# Expected complexity level and risk

1

# Testing

N/A

---------

Signed-off-by: joshua-spacetime <josh@clockworklabs.io>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
2026-02-19 03:59:33 +00:00
Jason Larabie 34aa9654fd Docs - add shared C++ version notice inside first C++ tab across docs (#4348)
# Description of Changes
- Added a shared component with a message for C++ on the version pinning
- Updated every doc that has a C++ tab to include the new message

# API and ABI breaking changes

N/A

# Expected complexity level and risk

2 - Small document change but used a shared component

# Testing
- [x] Tested locally with pnpm dev
- [x] Hosted on my personal site to double check the shared component
2026-02-19 00:20:47 +00:00
Noa ea0e01edb7 Fixes for procedure example in docs (#4346)
# Description of Changes

The maximum http timeout (500ms) was too low for the OpenAI API to have
time to respond, so I raised it, and verified that the rust and
typescript examples work. Csharp wasn't building at all for some reason
(`Workload installation failed: Unable to load the service index for
source https://api.nuget.org/v3/index.json.`?)

# Expected complexity level and risk

1

# Testing

- [x] Manually tested these changes
2026-02-18 23:21:23 +00:00
Jason Larabie 0590ab00f8 Rust docs updated for name to accessor (#4344)
# Description of Changes

- Updated all markdown files that call out `#[spacetimedb::table(name`
to `#[spacetimedb::table(accessor`
- Updated the LLM details on the same change

# API and ABI breaking changes

N/A

# Expected complexity level and risk

1 - Small rework in documentation to use the new 

# Testing

- [x] Did a small double check on name vs accessor locally
- [x] Codex tested all the LLM answers
2026-02-18 23:06:09 +00:00
Jason Larabie f9d4d2748d Small fixes for the Blackholio tutorial (#4343)
# Description of Changes
- Updated the tutorials to use `accessor` in place of `name` for Rust
table definitions
- Removed incorrect file listings for Connect reducer as it's now
private
- Fixed a bug in the Unreal tutorial to bind to correct method for error
handling

# API and ABI breaking changes

N/A

# Expected complexity level and risk
1- Documentation update only

# Testing
- [x] Tested the connect error build for Unreal
- [x] Discovered these issues through manual test of the tutorials
2026-02-18 19:45:16 +00:00
Ryan fc6e8fd21d [Docs] Revisions to Chat App doc for 2.0 release (#4335)
# Description of Changes

Updates the Chat App tutorial
`docs/docs/00100-intro/00300-tutorials/00100-chat-app.md`

* TypeScript (React) code snippet fixes
* Updated the initial `App.tsx` snippet to use `import type * as Types
from './module_bindings/types'` and type `systemMessages` as
`Types.Message[]`, matching the current template-generated bindings.
* Updated the placeholder `onlineUsers` / `offlineUsers` types in the
initial snippet to `Types.User[]`.
* Updated the `main.tsx` connection snippet with the template behavior
by sourcing `HOST` / `DB_NAME` from
`import.meta.env.VITE_SPACETIMEDB_HOST` / `VITE_SPACETIMEDB_DB_NAME` if
available.
* Removed an TypeScript example that referenced reducer event wiring
(`conn.reducers.onSendMessage(...)`) that doesn’t exist in the current
TS generated bindings.
* Updated the follow-up instruction text so the “replace `const
onlineUsers: ...`” and “replace `const offlineUsers: ...`” guidance
matches the updated `Types.User[]` placeholders in the earlier snippet.
* The tutorial section says arguments are JSON; the CLI will auto-quote
string args based on reducer parameter types, so the simple form
`send_message 'Hello, World!'` remains valid and is kept.
* Added C# Client SDK step to update `.csproj` file with `net8.0` and a
filter for code in the `spacetimedb` (server module) subdirectory.

# API and ABI breaking changes

N/A

# Expected complexity level and risk

1

# Testing

- [x] Performed documented operations locally.
2026-02-18 18:21:55 +00:00
Jason Larabie 96ba4ea742 Pinning C++ and Unreal to 1.12.0 (#4328)
# Description of Changes
A few small changes to pin the version:
- Updated the CMakeLists back from 2.0.0 to 1.12.0
- Updated the Unreal Blackholio tutorial documentation to target the
1.12.0 branch and not master
- Updated the Unreal Blackholio tutorial to call out 2.0 is coming soon
- Disabled the upgrade-version tool code path for C++ upgrades, but left
logic in place for the near future

# API and ABI breaking changes

N/A

# Expected complexity level and risk

1 - Docs change, config change, and blocking update path for C++

# Testing

- [x] Reviewed the docs
- [x] Tested update command locally
- [x] Tested `spacetime init` for `basic-cpp` and successfully built
2026-02-18 02:46:24 +00:00
Phoebe Goldman f33188ab1b Minor fixes to examples in event tables document (#4322)
# Description of Changes

Use `accessor =` rather than `name =` in Rust code snippet which defines
event table.

Add `schema` call and `export default` to TypeScript code snippet which
defines event table. I'm not sure this is better, and it's certainly
more cluttered, but the example as written you can't just copy/paste
into your module code.

# API and ABI breaking changes

N/a

# Expected complexity level and risk

Docs only

# Testing

Described elsewhere.
2026-02-17 21:33:31 +00:00
clockwork-labs-bot 3e71f4decf Docs: Expand FAQ for 2.0 launch (#4314)
Rewrites the FAQ from 5 basic questions to a comprehensive guide
covering:

- **General** — What is SpacetimeDB, is it only for games, is it
blockchain, licensing, self-hosting
- **Comparisons** — vs Mirror/Photon/networking libs, vs
Firebase/Supabase, vs PostgreSQL
- **Architecture** — Data persistence, real-time sync, reducers vs REST,
module languages, views, procedures
- **Development** — Getting started, `spacetime dev`, SQL usage,
Unity/Unreal/React/framework support, auth
- **Deployment** — Production publishing, hot-swapping modules, schema
migrations, size limits, pricing
- **Troubleshooting** — Global database names (401/403), confusing
generate errors, resetting databases

Content drawn from README, architecture docs, Zen of SpacetimeDB, and
common user questions from GitHub issues and Discord.

---------

Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
2026-02-17 05:56:47 +00:00
clockwork-labs-bot 8a2208bbcf docs: expand Maincloud deployment page (#4316)
Rewrites the Maincloud deployment guide from a bare-bones stub into a
comprehensive page. Addresses all three points from #3108 plus a
community request for the connection URI.

**New content:**

1. **Finding your module on the dashboard** - Direct URL
(`spacetimedb.com/my-module`) and profile page navigation
2. **Database lifecycle** - Running vs suspended states, automatic
suspension after inactivity, automatic resumption on first request
3. **Next steps section** - Links to dashboard, SpacetimeAuth setup,
quickstart guides, and usage monitoring

**Also added:**
- Prerequisites section (CLI install + `spacetime login` to link web
account)
- Publishing workflow (initial publish, hot-swap updates,
`--delete-data`)
- Client connection code examples for TypeScript, C#, Rust, and C++ with
the Maincloud host URL (`https://maincloud.spacetimedb.com`) - per
community request in #3108
- Database deletion instructions
- Link to pricing page

Closes #3108

---------

Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
2026-02-17 05:14:35 +00:00
Ryan e03b7d7516 Updated C# Name attribute to Accessor (#4306)
# Description of Changes

Implementation of #4295

Convert existing `Name` attribute to `Accessor` to support new Canonical
Case conversation of 2.0

# API and ABI breaking changes

Yes, in C# modules, we no longer use the attribute name `Name`, it
should now be `Accessor`

# Expected complexity level and risk

1

# Testing

- [X] Build and tested locally
- [X] Ran regression tests locally
2026-02-17 01:16:16 +00:00
Jeffrey Dallatezza 08ff1e1c11 TS Quickstart: Store different auth tokens for different servers/modules (#3252)
# Description of Changes

In the typescript quickstart example, this includes the server and
module name in the local storage variable name that we use for the auth
token.

This fixes an otherwise annoying issue people run into if they start
running the quickstart locally, then try to run it on maincloud. If they
have already run the app with a local server, their browser will store
the locally signed token, which will get rejected by maincloud.

# Expected complexity level and risk

1.

# Testing

I was able to connect to my local quickstart, then change the variables
to point to a module on maincloud, and I didn't get any errors.

Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
2026-02-16 16:34:46 +00:00
Shubham Mishra e4098f98d9 Rust: macro change name -> accessor (#4264)
## Description of Changes

This PR primarily affects the `bindings-macro` and `schema` crates to
review:

### Core changes

1. Replaces the `name` macro with `accessor` for **Tables, Views,
Procedures, and Reducers** in Rust modules.
2. Extends `RawModuleDefV10` with a new section for:

   * case conversion policies
   * explicit names
    New sections are not validated in this PR so not functional.
3. Updates index behavior:

* Index names are now always **system-generated** for clients. Which
will be fixed in follow-up PR when we start validating RawModuleDef with
explicit names.
   * The `accessor` name for an index is used only inside the module.


## Breaking changes (API/ABI)

1. **Rust modules**

   * The `name` macro must be replaced with `accessor`.

2. **Client bindings (all languages)**

* Index names are now system-generated instead of using explicitly
provided names.


**Complexity:** 3

A follow-up PR will reintroduce explicit names with support for case
conversion.

---------

Co-authored-by: rekhoff <r.ekhoff@clockworklabs.io>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <bot@clockworklabs.com>
2026-02-16 15:23:50 +00:00
Julien Lavocat 83851fe9df Add Angular integration (#4139)
# Description of Changes

- Add Angular integration
- Add Angular quickstart chat template

# API and ABI breaking changes

None.

# Expected complexity level and risk

2

# Testing

Ran the template

---------

Co-authored-by: Tien Pham <tien@clockworklabs.io>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
2026-02-16 02:21:52 +00:00
Piotr Sarnacki 4c962b9170 spacetime.json config implementation (#4199)
# Description of Changes

This PR implements support for the `spacetime.json` configuration file
that can be used to set up common `generate` and `publish` targets. An
example of `spacetime.json` could look like this:

```
{
  "dev_run": "pnpm dev",
  "generate": [
    { "out-dir": "./foobar", "module-path": "region-module", "language": "c-sharp" },
    { "out-dir": "./global", "module-path": "global-module", "language": "c-sharp" },
  ],
  "publish": {
    "database": "bitcraft",
    "module-path": "spacetimedb",
    "server": "local",
    "children": [
      { "database": "region-1", "module-path": "region-module", server: "local" },
      { "database": "region-2", "module-path": "region-module", server: "local" }
    ]
  }
}
```

With this config, running `spacetime generate` without any arguments
would generate bindings for two targets: `region-module` and
`global-module`. `spacetime publish` without any arguments would publish
three modules, starting from the parent: `bitcraft`, `region-1`, and
`region-2`. On top of that, the command `pnpm dev` would be executed
when using `spacetime dev`.

It is also possible to pass additional command line arguments when
calling the `publish` and `generate` commands, but there are certain
limitations. There is a special case when passing either a module path
to generate or a module name to publish. Doing that will filter out
entries in the config file that do not match. For example, running:

```
spacetime generate --project-path global-module
```

would only generate bindings for the second entry in the `generate`
list.

In a similar fashion, running:

```
spacetime publish region-1
```

would only publish the child database with the name `region-1`

Passing other existing arguments is also possible, but not all of the
arguments are available for multiple configs. For example, when running
`spacetime publish --server maincloud`, the publish command would be
applied to all of the modules listed in the config file, but the
`server` value from the command line arguments would take precedence.
Running with arguments like `--bin-path` would, however, would throw an
error as `--bin-path` makes sense only in a context of a specific
module, thus this wouldn't work: `spacetime publish --bin-path
spacetimedb/target/debug/bitcraft.wasm`. I will throw an error unless
there is only one entry to process, thus `spacetime publish --bin-path
spacetimedb/target/debug/bitcraft.wasm bitcraft` would work, as it
filters the publish targets to one entry.

# API and ABI breaking changes

None

# Expected complexity level and risk

3

The config file in itself is not overly complex, but when coupled with
the CLI it is somewhat tricky to get right. There are also some changes
that I had to make to how clap arguments are validated - because the
values can now come from both the config file and the clap config, we
can't use some of the built-in validations like `required`, or at least
I haven't found a clean way to do so.

# Testing

I've added some automated tests, but more tests and manual testing is
coming.

---------

Signed-off-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Co-authored-by: bradleyshep <148254416+bradleyshep@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: = <cloutiertyler@gmail.com>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
2026-02-15 23:22:44 +00:00
Tyler Cloutier 3f58b5951b Implement event tables (server, Rust/TS/C# codegen + client SDKs) (#4217)
## Summary

Implements event tables end-to-end: server datastore, module bindings
(Rust/TypeScript/C#), client codegen (Rust/TypeScript/C#), client SDKs
(Rust/TypeScript/C#), and integration tests.

Event tables are tables whose rows are ephemeral — they persist to the
commitlog and are delivered to V2 subscribers, but are NOT merged into
committed state. Rows are only visible within the transaction that
inserted them. This is the mechanism that replaces reducer event
callbacks in 2.0.

## What's included

### Server
- `is_event` flag on `RawTableDefV10`, `TableDef`, `TableSchema`
- Event table rows recorded in TxData but skipped during committed state
merge
- Commitlog replay treats event table inserts as no-ops
- Migration validation rejects changing `is_event` between module
versions
- `SELECT * FROM *` excludes event tables
- V1 WebSocket subscriptions to event tables rejected with upgrade
message
- V2 subscription path delivers event table rows correctly
- `CanBeLookupTable` trait — event tables cannot be lookup tables in
semijoins
- Runtime view validation rejects event tables

### Module bindings
- **Rust**: `#[spacetimedb::table(name = my_events, public, event)]`
- **TypeScript**: `table({ event: true }, ...)`
- **C#**: `[Table(Event = true)]`

### Client codegen (`crates/codegen/`)
- **Rust**: Generates `EventTable` impl (insert-only) for event tables,
`Table` impl for normal tables. `CanBeLookupTable` emitted for non-event
tables.
- **TypeScript**: Emits `event: true` in generated table schemas.
`ClientTableCore` type excludes `onDelete`/`onUpdate` for event tables
via conditional types.
- **C#**: Generates classes inheriting from `RemoteEventTableHandle`
(which hides `OnDelete`/`OnBeforeDelete`/`OnUpdate`) for event tables.

### Client SDKs
- **Rust**: `EventTable` trait with insert-only callbacks, client cache
bypass, `count()` returns 0, `iter()` returns empty
- **TypeScript**: Event table cache bypass in `table_cache.ts` — fires
`onInsert` callbacks but doesn't store rows. Type-level narrowing
excludes delete/update methods.
- **C#**: `RemoteEventTableHandle` base class hides delete/update
events. Parse/Apply/PostApply handle `EventTableRows` wire format, skip
cache storage, fire only `OnInsert`.

### Tests
- 9 datastore unit tests (insert/delete/update semantics, replay,
constraints, indexes, auto-inc, cross-tx reset)
- 3 Rust SDK integration tests (basic events, multiple events per
reducer, no persistence across transactions)
- Codegen snapshot tests (Rust, TypeScript, C#)
- Trybuild compile tests (event tables rejected as semijoin lookup
tables)

## Deferred
- `on_delete` codegen for event tables (server only sends inserts;
client synthesis deferred)
- Event tables in subscription joins / views (well-defined but
restricted for now)
- C++ SDK support
- RLS integration test

## API and ABI breaking changes

- `is_event: bool` added to `RawTableDefV10` (appended, defaults to
`false` — existing modules unaffected)
- `CanBeLookupTable` trait bound on semijoin methods in query builder
(all non-event tables implement it, so existing code compiles unchanged)
- `RemoteEventTableHandle` added to C# SDK (new base class for generated
event table handles)

## Expected complexity level and risk

3 — Changes touch the schema pipeline end-to-end and all three client
SDKs, but each individual change is straightforward. The core risk area
is the committed state merge skip in `committed_state.rs`. Client SDK
changes are additive (new code paths for event tables, existing paths
unchanged).

## Testing

- [x] `cargo clippy --workspace --tests --benches` passes
- [x] `cargo test -p spacetimedb-codegen` (snapshot tests)
- [x] `cargo test -p spacetimedb-datastore --features
spacetimedb-schema/test -- event_table` (9 unit tests)
- [x] `pnpm format` passes
- [x] Rust SDK integration tests pass (`event_table_tests` module)

---------

Signed-off-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Co-authored-by: Phoebe Goldman <phoebe@goldman-tribe.org>
Co-authored-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: joshua-spacetime <josh@clockworklabs.io>
2026-02-15 22:56:20 +00:00
Jason Larabie 495064a565 Fix Unreal Blackholio Tutorial for project rename (#4044)
# Description of Changes

Fixes a problem with renaming the project from client_unreal to
blackholio which causes the C++ header code to be incorrect

# API and ABI breaking changes

N/A

# Expected complexity level and risk

1 - Updates a small portion of the Unreal Tutorial documentation

# Testing

Testing the current docs is what found the issue.

- [x] Rebuilt the Unreal Blackholio from the tutorial

---------

Signed-off-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
2026-02-13 14:43:52 +00:00
Noa c044d96a7a [TS] schema() takes an object (#4273)
# Description of Changes

Implements the rest of the casing proposal.

# Expected complexity level and risk

<!--
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! -->

- [ ] <!-- maybe a test you want to do -->
- [ ] <!-- maybe a test you want a reviewer to do, so they can check it
off when they're satisfied. -->
2026-02-13 07:53:42 +00:00
Tyler Cloutier 2ec07a3f70 Standardize query builder syntax across Rust, TypeScript, and C# (Server/Client) (#4261)
# Description of Changes

Standardizes the query builder API across all three language SDKs (Rust,
TypeScript, C#) for consistency.

**Rust:**
- Rename `Query` struct to `RawQuery`, make `Query` a trait with `fn
into_sql(self) -> String`
- All builder types (`Table`, `FromWhere`, `LeftSemiJoin`,
`RightSemiJoin`) implement `Query<T>` trait
- Views can return `-> impl Query<T>` instead of specifying exact
builder types
- The `#[view]` macro auto-detects `impl Query<T>` and rewrites to
`RawQuery<T>`
- Add `Not` variant to `BoolExpr` with `.not()` method

**TypeScript:**
- Add `ne()` to `ColumnExpression`
- Refactor `BooleanExpr` to `BoolExpr` class with chainable `.and()`,
`.or()`, `.not()` methods
- Make builders valid queries directly (`.build()` deprecated but still
works)
- Deprecate `from()` wrapper — use `tables.person.where(...)` directly
- Merge `query` export into `tables` so table refs are also query
builders
- Add subscription callback form: `subscribe(ctx =>
ctx.from.person.where(...))`
- Unify `useTable` with query builder syntax; deprecate `filter.ts`

**C#:**
- Add `Not()` method to `BoolExpr<TRow>`
- Add `IQuery<TRow>` interface implemented by all builder types
(`Table`, `FromWhere`, `LeftSemiJoin`, `RightSemiJoin`, `Query`)
- Add `ToSql()` to all builder types so `.Build()` is no longer required
- Update `AddQuery` to accept `IQuery<TRow>` instead of `Query<TRow>`

# API and ABI breaking changes

- Rust: `Query<T>` is now a trait (was a struct). The struct is renamed
to `RawQuery<T>`. This is a breaking change for any code that used
`Query<T>` as a type directly.
- TypeScript: `BooleanExpr` is now a `BoolExpr` class (was a
discriminated union type). The `query` export is deprecated in favor of
`tables`.
- C#: `AddQuery` now accepts `Func<QueryBuilder, IQuery<TRow>>` instead
of `Func<QueryBuilder, Query<TRow>>`. Existing `.Build()` calls still
work since `Query<TRow>` implements `IQuery<TRow>`.

# Expected complexity level and risk

3 — Changes touch multiple language SDKs and codegen, but each
individual change is straightforward. The Rust macro rewrite for `impl
Query<T>` detection is the most complex piece. All existing
`.build()`/`.Build()` calls continue to work.

# Testing

- [x] `cargo test -p spacetimedb-query-builder` — 16/16 tests pass
- [x] `cargo check -p spacetimedb` — clean, no warnings
- [x] `cargo check` on views-query, views-sql, views-basic,
views-trapped smoketest modules — all clean
- [x] `cargo test -p spacetimedb-codegen codegen_csharp` — snapshot
updated, passes
- [x] `npm test` (TypeScript) — 101/101 tests pass
- [x] C# QueryBuilder tests — new tests for `Not()`, `IQuery<T>`
interface
- [ ] CI passes
2026-02-13 04:22:49 +00:00
Phoebe Goldman 1592dec8af Update Rust client SDK for V2 WebSocket format (#4257)
# Description of Changes

Update the Rust client SDK to use the new V2 WebSocket format, and
present the V2 user-facing API.

## Reducer events

### Remove on-reducer callbacks

It's no longer possible to observe reducers called by other clients by
registering callbacks with `ctx.reducers.on_{my_reducer}`. We no longer
code-generate those methods, or the associated
`ctx.reducers.remove_on_{my_reducer}`. Internal plumbing for storing and
invoking those callbacks is also removed.

### Add specific reducer invocation callbacks

In addition to the previous way to invoke reducers,
`ctx.reducers.{my_reducer}(args...)`, we add a method that registers a
callback to run after the reducer is finished. This method has the
suffix `_then`, as in `ctx.reducers.{my_reducer}_then(args...,
callback)`.

The callback will accept two arguments:
- `ctx: &ReducerEventContext`, the same context as was previously passed
to on-reducer callbacks.
- `status: Result<Result<(), String>, InternalError>`, denoting the
outcome of the reducer.
- `Ok(Ok(())` means the reducer committed. This corresponds to
`ReducerOutcome::Ok` or `ReducerOutcome::Okmpty` in the new WS format.
- `Ok(Err(message))` means the reducer returned an "expected" or "user"
error. This corresponds to `ReducerOutcome::Err` in the new WS format.
- `Err(internal_error)` means something went wrong with host execution.
This corresponds to `ReducerOutcome::InternalError` in the new WS
format.

Internally, the SDK stores the callbacks in its `ReducerCallbacks` map.
This is keyed on `request_id: u32`, a number that is generated for each
reducer call (from an `AtomicU32` that we increment each time), and
included in the `ClientMessage::CallReducer` request. The
`ServerMessage::ReducerResult` includes the same `request_id`, so the
SDK pops out of the `ReducerCallbacks` and invokes the appropriate
callback when processing that message.

These new callbacks are very similar to the existing procedure
callbacks.

### The `Event` exposed to row callbacks

Row callbacks caused by a reducer invoked by this client will see
`Event::Reducer`, the same as they would prior to this PR. These
callbacks will be the result of a `ServerMessage::ReducerResult` with
`ReducerOutcome::Ok`. In order to expose the reducer name and arguments
to this event, the client stores them in its `ReducerCallbacks` map,
alongside the callback for when the reducer is complete.

Row callbacks caused by any other reducer, or any non-reducer
transaction, are now indistinguishable to the client. These will see
`Event::Transaction`, which is renamed from the old
`Event::UnknownTransaction`.

### Less metadata in `ReducerEvent`

Some metadata is removed from `ReducerEvent`, as the V2 WebSocket format
no longer publishes it, even to the caller.

## `CallReducerFlags` are removed

All machinery for setting, storing and applying call reducer flags is
removed from the SDK, as the new WS format does not have any non-default
flags.

## Requesting rows in unsubscribe

When sending a `ClientMessage::Unsubscribe`, we always request that the
server include the matching rows in its response
`ServerMessage::UnsubscribeApplied`. This saves us having to update the
SDK to store query sets separately, at least for now. (We'll do that
later.)

## Handling rows

The new SDK does some additional parsing to wrangle rows in the new
WebSocket format into the same internal data structures as before,
rather than re-writing the client cache. (We'll do that later.)
Specifically, parsing of `DbUpdate` is changed so that:

- We parse raw `TransactionUpdate` into the generated `DbUpdate` type,
which requires an additional loop compared to the previous version, to
cope with the new WS format's dividing updates by query set. We define a
function `transaction_update_iter_table_updates` which encapsulates this
nested loop in an iterator.
- We have two new functions for parsing raw `QueryRows` into the
generated `DbUpdate` type, one for when they come from a
`SubscribeApplied`, and the other when they come from an
`UnsubscribeApplied`. `QueryRows` from `SubscribeApplied` translate to a
`DbUpdate` of all inserts, while one from `UnsubscribeApplied` will be
all deletes.

## Legacy subscriptions

"Legacy subscriptions" are removed. These were only used for
`subscribe_to_all_tables`, which as of now is stubbed. I will follow up
with a change to re-implement `subscribe_to_all_tables` by
code-generating a list of all known tables, and having it subscribe to
`select * from {table}` for every table in that list.

## `subscribe_to_all_tables` via a list

Previously, `subscribe_to_all_tables` worked by sending a legacy
subscription with the query `SELECT * FROM *`, which the host had
special handling to expand to subscribing to all tables. As legacy
subscriptions are no longer usable in V2 clients, this can't work.
Instead, we code-generate `SpacetimeModule::ALL_TABLE_NAMES`, a list of
all the known table names. `subscribe_to_all_tables` then maps across
this list to construct a list of queries in the form `SELECT * FROM
{table_name}`, and subscribes to all of those queries. This has the
upside that defining a new table in the module without regenerating
client bindings will no longer result in the client seeing rows of
tables it does not know about and cannot parse.

## Light mode removed

Light mode is no longer meaningful in the V2 WS format, so all code
related to it is removed.

## Internal changes

### Renamed WS messages

The SDK's internal code is updated to account for various renames:

- `QueryId` -> `QuerySetId`, `query_id` -> `query_set_id`.
- `SubscribeMulti` -> `Subscribe`, `UnsubscribeMulti` -> `Unsubscribe`.

## Incidental changes in this PR, not necessary for other client SDKs

### Don't filter out empty ranges in `RowSizeHint`

The Rust implementation of `RowSizeHint` in `BsatnRowList` got regressed
in the base branch to not work with zero-sized rows. This change fixes
that.

# API and ABI breaking changes

Boy howdy is it!

# Expected complexity level and risk

3? Changes ended up being less complicated than I feared, but we do have
some fiddly code here, and we have internal dependencies on the SDK.

# 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! -->

- [x] Updated automated test suite.
  - Known failures:
- [ ] `subscribe_all_select_star`, which is currently broken because
it's trying to subscribe to rows from private tables. #4241 will fix
this.

---------

Co-authored-by: Jeffrey Dallatezza <jeffreydallatezza@gmail.com>
Co-authored-by: = <cloutiertyler@gmail.com>
2026-02-13 01:08:37 +00:00
clockwork-tien 99edb2954c feat: Quickstart and client for TanStack Start (#4107)
# Description of Changes
- Quickstart template `tanstack-ts` and client for TanStack Start
- Add Vue Quickstart Docs

<!-- Please describe your change, mention any related tickets, and so on
here. -->

# Screenshots
- `tanstack-ts` template
<img width="1461" height="898" alt="image"
src="https://github.com/user-attachments/assets/6b7e5473-33c4-4f76-92a7-18607c74422c"
/>

- TanStack Start Quickstart Docs
<img width="1459" height="896" alt="image"
src="https://github.com/user-attachments/assets/b7557498-ff5a-4ce5-9c85-68db943e1b9a"
/>

# API and ABI breaking changes

<!-- If this is an API or ABI breaking change, please apply the
corresponding GitHub label. -->

# Expected complexity level and risk

<!--
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! -->

- [x] Tested the templates locally (e.g. able to add people), works well
for me
2026-02-12 15:14:32 +00:00
joshua-spacetime eb2f7a3535 Add missing query builder docs (#4196)
# Description of Changes

Document the client query builder api for rust, csharp, and typescript.
Also add/fix some documentation for the module-side query builder.

# API and ABI breaking changes

N/A

# Expected complexity level and risk

0

# Testing

N/A. Just documentation.

---------

Signed-off-by: joshua-spacetime <josh@clockworklabs.io>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
2026-02-12 07:31:15 +00:00
Phoebe Goldman 98585e858d Rename with_module_name -> with_database_name (#4267)
# Description of Changes

Modules are like programs, databases are like processes. Your client
connects to a remote database, not a remote module.

<!-- Please describe your change, mention any related tickets, and so on
here. -->

# API and ABI breaking changes

Yep!

# Expected complexity level and risk

2? I made this change with find + replace, and it's possible that I
borked the edit, or missed some reference somehow. It seems unlikely,
however, that this change will have deeper implications we haven't
considered.

# Testing

N/a
2026-02-12 02:11:33 +00:00
Noa 7677b5478f [TS] Export reducers, etc from a module (#4220)
# Description of Changes

Haven't changed `schema()` to accept an object yet, maybe that's for a
followup?

Now everything exported from the module must be exported from the
typescript module.

# Expected complexity level and risk

<!--
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! -->

- [ ] <!-- maybe a test you want to do -->
- [ ] <!-- maybe a test you want a reviewer to do, so they can check it
off when they're satisfied. -->
2026-02-11 22:45:36 +00:00
bradleyshep 41d793f904 Deno quickstart (#4191)
# Description of Changes

Adds a Deno quickstart template and documentation.

**Template (`templates/deno-ts/`):**
- `deno.json` with tasks and import map for spacetimedb
- `src/main.ts` using Deno-native APIs (`Deno.stdin`,
`Deno.readTextFile`, `Deno.writeTextFile`, `Deno.env`)
- `spacetimedb/` server module (TypeScript)
- Pre-generated `module_bindings/`

**Documentation
(`docs/docs/00100-intro/00200-quickstarts/00275-deno.md`):**
- Step-by-step quickstart following existing pattern
- Covers project structure, tables/reducers, running the client, CLI
usage
- Documents Deno-specific features: permissions, built-in TypeScript,
import maps, no node_modules
- Explains `--unstable-sloppy-imports` flag (required because generated
bindings use extensionless imports)

# API and ABI breaking changes

None. This is a new template and documentation addition.

# Expected complexity level and risk

**1** - Trivial addition. New template files and documentation only, no
changes to existing code or generator.

# Testing

- [x] Server module publishes successfully
- [x] Bindings generate correctly
- [x] Run `deno task start` and verify connection to SpacetimeDB
- [x] Test interactive CLI commands: add names, `list`, `hello`
2026-02-11 22:04:44 +00:00
clockwork-tien 132112b435 feat: Quickstart and client for Nuxt (#4176)
# Description of Changes

The PR implements the following updates:
- Create `nuxt-ts` template
- Add Nuxt Quickstart Docs

<!-- Please describe your change, mention any related tickets, and so on
here. -->

# Screenshots
- `nuxt-ts` template
<img width="1446" height="894" alt="image"
src="https://github.com/user-attachments/assets/743a946a-3570-4c0b-823a-c919be722d0a"
/>

- Nuxt Quickstart Docs
<img width="1460" height="898" alt="image"
src="https://github.com/user-attachments/assets/a7014d04-6dc1-4e1d-ac39-051c9ef7c09e"
/>


# API and ABI breaking changes

<!-- If this is an API or ABI breaking change, please apply the
corresponding GitHub label. -->

# Expected complexity level and risk

<!--
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! -->

- [ ] <!-- maybe a test you want to do -->
- [ ] <!-- maybe a test you want a reviewer to do, so they can check it
off when they're satisfied. -->

---------

Co-authored-by: = <cloutiertyler@gmail.com>
2026-02-11 20:04:48 +00:00
Jason Larabie c59ee1ddc3 [2.0 Breaking] Add --include-private and default private tables to not generate (#4241)
# Description of Changes
Updated the codegen table/function iteration functions to take in a
parameter to check visibility in all locations for the supported
languages.
- Updated the util.rs functions for iterating tables/functions to check
for a CodegenVisibility enum (IncludePrivate, or OnlyPublic)
- Added a new CodegenOptions struct to pass around the CodegenVisibility
and future flags, defaulted visibility to OnlyPublic
- Updated the CLI to return a list of all private tables not included
(added a TODO to check the --include-private opt):
```bash
Optimising module with wasm-opt...
Build finished successfully.
Skipping private tables during codegen: secret_note, secret_order, secret_person.
Generate finished successfully.
```

# API and ABI breaking changes

Technically API breaking as the private tables will no longer be
available. (GitHub labels are not working at the moment)

# Expected complexity level and risk

1 - Simple change the testing took longer

# Testing

Turns out when you remove private tables you invalidate most of the
module_bindings across the system!

- [x] Rust test SDK for all languages
- [x] C# SDK tests
- [x] C# dotnet tests
- [x] Updated and checked snap files
- [x] Updated Blackholio (Unreal + Unity) module_bindings and tested
- [x] Ran Unreal SDK tests

---------

Signed-off-by: Jason Larabie <jason@clockworklabs.io>
2026-02-12 03:08:54 +00:00
joshua-spacetime e1769b5a24 Add warning prompt for 1.0 -> 2.0 module upgrade path (#4247)
# Description of Changes

Adds a warning prompt for 1.0 -> 2.0 module upgrade path.

# API and ABI breaking changes

None

# Expected complexity level and risk

1

# Testing

This patch checks a wasm module binary compiled with pre-2.0 bindings
into source control. A smoketest was added that first publishes the the
pre-compiled module and then publishes a new module using the 2.0
bindings in its place.
2026-02-11 18:56:08 +00:00
bradleyshep 9de9d06a36 Quickstart remix (#4113)
# Description of Changes

Adds a Remix quickstart template and documentation for SpacetimeDB.

## Template (`templates/remix-ts/`)
- SpacetimeDB module with TypeScript (`spacetimedb/src/index.ts`)
- Remix app with Vite configuration
- SpacetimeDB provider in `app/providers.tsx` with proper SSR/hydration
handling
- Example route (`app/routes/_index.tsx`) demonstrating `useTable` and
`useReducer` hooks
- Pre-generated module bindings in `src/module_bindings/`

## Documentation
(`docs/docs/00100-intro/00200-quickstarts/00175-remix.md`)
- Step-by-step quickstart guide following existing pattern
- Covers project creation with `spacetime dev --template remix-ts`
- Explains project structure, provider pattern, and React hooks usage
- Documents environment variable configuration (`VITE_SPACETIMEDB_HOST`,
`VITE_SPACETIMEDB_DB_NAME`)

## Consistency
- Environment variables follow the same `HOST`/`DB_NAME` naming
convention as other quickstarts
- Documentation structure mirrors Next.js and React quickstarts
- Dev server runs on port 3001 to avoid conflict with SpacetimeDB on
port 3000

# API and ABI breaking changes

None.

# Expected complexity level and risk

1 - Additive change only. New template and documentation, no
modifications to existing functionality.

# Testing

- [ ] Run `spacetime dev --template remix-ts my-remix-app` and verify
app starts
- [ ] Verify SpacetimeDB connection works at http://localhost:3001
- [ ] Test adding a person via the UI form
- [ ] Verify SSR doesn't crash (SpacetimeDB provider defers to
client-side)
- [ ] Check documentation renders correctly in Docusaurus
2026-02-11 18:50:41 +00:00
Jason Larabie 440cc19d3c Added C++ smoketest for quickstart-chat + updated chat doc (#4109)
# Description of Changes

- Updated the chat tutorial to include blocks for C++ server code
- Updated the Python smoketests to allow C++ with the quickstart check

# API and ABI breaking changes

N/A

# Expected complexity level and risk

1 - Small changes to get the C++ modules to be tested through quickstart

# Testing

- [x] Ran the tests locally
2026-02-11 18:43:17 +00:00
bradleyshep e50b5f3930 LLM Oneshot Prompts, Oneshotted Apps, and Cursor Rules (C#/Rust/TS) (#4032)
# Description of Changes

This PR introduces an **LLM One-Shot App Generation** benchmarking
framework and comprehensive **Cursor rules for SpacetimeDB
development**.

**Cursor Rules (`docs/.cursor/rules/`):**
- `spacetimedb.mdc` - General SpacetimeDB concepts and architecture
- `spacetimedb-csharp.mdc` - C# module and client patterns
- `spacetimedb-rust.mdc` - Rust module development
- `spacetimedb-typescript.mdc` - TypeScript SDK usage

**LLM One-Shot Framework (`tools/llm-oneshot/`):**
- Benchmarking tool to measure how well AI can one-shot SpacetimeDB apps
- Composable prompt system with 12 cumulative feature levels (basic chat
→ full-featured with threading, permissions, presence, etc.)
- Support for 4 tech stacks: TypeScript+SpacetimeDB,
TypeScript+PostgreSQL, Rust+SpacetimeDB, C#+SpacetimeDB
- Additional Cursor rules for deployment, grading, and frontend patterns

**Sample One-Shotted Apps:**
- Multiple chat-app implementations (TypeScript, Rust, C#/MAUI)
- Multiple paint-app implementations (TypeScript, Rust, C#/MAUI)

# API and ABI breaking changes

None - this is a documentation and tooling addition only.

# Expected complexity level and risk

**1** - Trivial addition of documentation, tooling, and example
applications. No changes to core SpacetimeDB functionality. The
`tools/llm-oneshot/` folder is entirely self-contained and the Cursor
rules in `docs/` are purely informational.

# Testing

- [ ] Verified Cursor rules load correctly in IDE
- [ ] Ran one-shot generation with various prompt levels to validate
rules work
- [ ] Sample apps compile and deploy correctly
2026-02-11 18:24:20 +00:00
bradleyshep fe9ad4c909 Quickstart nextjs (#4097)
# Description of Changes

Adds a new Next.js quickstart template and documentation.

**New Template (`templates/nextjs-ts/`):**
- Next.js 15 App Router with TypeScript SpacetimeDB module
- Pre-configured `SpacetimeDBProvider` with client-side connection
handling
- Environment variable support (`NEXT_PUBLIC_SPACETIMEDB_HOST`,
`NEXT_PUBLIC_SPACETIMEDB_DB_NAME`)
- SSR-safe implementation with `"use client"` directives
- Example page demonstrating `useTable` and `useReducer` hooks
- Dev server runs on port 3001 to avoid conflict with SpacetimeDB on
port 3000
- Pre-generated module bindings included

**New Documentation (`docs/.../00200-nextjs.md`):**
- 8-step quickstart consistent with other quickstarts (React,
TypeScript, Rust, C#)
- Covers: project creation, structure, tables/reducers, CLI testing
- Next.js-specific: provider pattern, SSR considerations, env var
configuration, React hooks usage

**Updated `templates-list.json`:**
- Added `nextjs-ts` to highlights and templates list

# API and ABI breaking changes

None.

# Expected complexity level and risk

1 - Adds a new template and docs without modifying existing
functionality.

# Testing

- [ ] Run `spacetime dev --template nextjs-ts my-test-app` and verify
the app starts
- [ ] Navigate to http://localhost:3001 and confirm the UI loads and
connects
- [ ] Add a person via the UI and verify it appears in the list
- [ ] Verify env vars work: set `NEXT_PUBLIC_SPACETIMEDB_URI` and
`NEXT_PUBLIC_SPACETIMEDB_MODULE`
- [ ] Verify the quickstart doc renders correctly in the docs site
- [ ] Confirm Next.js appears in the sidebar after React
2026-02-11 16:29:25 +00:00
bradleyshep 0ed052eb0d Quickstart nodejs (#4112)
# Description of Changes

Adds a Node.js quickstart template and documentation for SpacetimeDB.

## Template (`templates/nodejs-ts/`)
- SpacetimeDB module with TypeScript (`spacetimedb/src/index.ts`)
- Node.js client with interactive CLI (`src/main.ts`)
- File-based token persistence (`.spacetimedb-token`) instead of
localStorage
- Table change callbacks (`onInsert`, `onDelete`)
- Graceful shutdown handlers for `SIGINT`/`SIGTERM`
- Pre-generated module bindings in `src/module_bindings/`

## Documentation
(`docs/docs/00100-intro/00200-quickstarts/00300-nodejs.md`)
- Step-by-step quickstart guide following existing pattern
- Covers project creation with `spacetime dev --template nodejs-ts`
- Explains project structure and client code
- Documents interactive CLI commands (`list`, `hello`, `<name>`)
- Covers Node.js-specific considerations (WebSocket support, token
storage)
- Documents environment variable configuration (`SPACETIMEDB_HOST`,
`SPACETIMEDB_DB_NAME`)

## Consistency
- Environment variables follow the same `HOST`/`DB_NAME` naming
convention as other quickstarts
- Documentation structure mirrors React and Next.js quickstarts

# API and ABI breaking changes

None.

# Expected complexity level and risk

1 - Additive change only. New template and documentation, no
modifications to existing functionality.

# Testing

- [ ] Run `spacetime dev --template nodejs-ts` and verify project
initializes
- [ ] Run `npm run dev` and verify connection to SpacetimeDB
- [ ] Test adding a person by typing a name
- [ ] Test `list` command shows all people
- [ ] Test `hello` command calls reducer (check server logs)
- [ ] Verify token persistence works across restarts
- [ ] Test graceful shutdown with Ctrl+C
- [ ] Check documentation renders correctly
2026-02-11 16:15:50 +00:00
bradleyshep dd99be6891 Quickstart bun (#4154)
# Description of Changes

Adds a Bun quickstart template and documentation for SpacetimeDB.

## Template (`templates/bun-ts/`)
- SpacetimeDB module with TypeScript (`spacetimedb/src/index.ts`)
- Bun client with interactive CLI (`src/main.ts`)
- Uses Bun-native APIs (`Bun.file()`, `Bun.write()`) for token
persistence
- Uses Bun's native WebSocket and TypeScript support
- Pre-generated module bindings in `src/module_bindings/`

## Documentation
(`docs/docs/00100-intro/00200-quickstarts/00250-bun.md`)
- Step-by-step quickstart guide following existing pattern
- Covers project creation with `spacetime dev --template bun-ts`
- Explains project structure and Bun-specific client code
- Documents environment variable configuration (`SPACETIMEDB_HOST`,
`SPACETIMEDB_DB_NAME`)
- Highlights Bun-specific features (native WebSocket, built-in
TypeScript, `.env` support)

## Consistency
- Environment variables follow the same `HOST`/`DB_NAME` naming
convention as other quickstarts
- Documentation structure mirrors Node.js quickstart
- Interactive CLI mirrors Node.js template behavior

# API and ABI breaking changes

None.

# Expected complexity level and risk

1 - Additive change only. New template and documentation, no
modifications to existing functionality.

# Testing

- [ ] Run `spacetime dev --template bun-ts my-bun-app` and verify app
starts
- [ ] Verify SpacetimeDB connection works via WebSocket
- [ ] Test adding a person via the interactive CLI
- [ ] Verify real-time subscription updates appear in client
- [ ] Check documentation renders correctly in Docusaurus
2026-02-11 16:07:01 +00:00
clockwork-tien aca374a781 feat: Quickstart and client for Plain JS Script Tags (#4161)
# Description of Changes

The PR implements the following updates:

- Create a quickstart guide and client support for using SpacetimeDB
directly in browser with script tags
- A template to easily work with/test the implementation and get started
with script tags

The bundle is served via
`https://unpkg.com/spacetimedb@latest/dist/browser.bundle.js`, which
only works after the package is published to npm, therefore to test
locally we can use the `browser-ts` template and local bundle:
1. Build local bundle
```
cd crates/bindings-typescript
pnpm install
pnpm build
```
2. Use local bundle built in template`index.html` (swap the URL from
`unpkg`)
```diff
- <script src="https://unpkg.com/spacetimedb@latest/dist/browser.bundle.js"></script>
+ <script src="../../crates/bindings-typescript/dist/browser.bundle.js"></script>
```
3. Open `browser-ts/index.html` directly in browser along with
`spacetime start` + publish the module `spacetime publish --project-path
spacetimedb browser-ts`

# Screenshots

<img width="1106" height="707" alt="image"
src="https://github.com/user-attachments/assets/715bea26-f54b-42be-97f9-79dcd57d153f"
/>

<img width="1490" height="855" alt="image"
src="https://github.com/user-attachments/assets/2b1aeaf9-22ba-4ae6-bc63-771805b8c2b9"
/>


<!-- Please describe your change, mention any related tickets, and so on
here. -->

# API and ABI breaking changes

<!-- If this is an API or ABI breaking change, please apply the
corresponding GitHub label. -->

# Expected complexity level and risk

<!--
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! -->

- [ ] <!-- maybe a test you want to do -->
- [ ] <!-- maybe a test you want a reviewer to do, so they can check it
off when they're satisfied. -->

---------

Co-authored-by: = <cloutiertyler@gmail.com>
2026-02-11 11:09:10 +00:00
Jason Larabie bb8fd49936 Docs Update for C++ [2/4] (#4129)
# Description of Changes

In order to give reviewers a chance to finish in one session the docs
are getting split up for the C++ update. This pass contains the
following section update:
- Tables

# API and ABI breaking changes

N/A

# Expected complexity level and risk

1 - Just documentation additions

# Testing

- [x] Manually tested each block
2026-02-10 23:03:01 +00:00
Jason Larabie fc94dd85cc Docs Update for C++ [4/4] (Blackholio) (#4169)
# Description of Changes

In order to give reviewers a chance to finish in one session the docs
are getting split up for the C++ update. This pass contains the
following section update:
- Unity Blackholio Tutorial
- Unreal Blackholio Tutorial
- Added /demo/Blackholio/server-cpp

# API and ABI breaking changes

N/A

# Expected complexity level and risk

1 - Just documentation additions

# Testing

- [x] Manually tested each block
2026-02-10 21:37:16 +00:00
Jason Larabie 19302708db Docs Update for C++ [3/4] (#4163)
# Description of Changes

In order to give reviewers a chance to finish in one session the docs
are getting split up for the C++ update. This pass contains the
following section update:
- Functions

# API and ABI breaking changes

N/A

# Expected complexity level and risk

1 - Just documentation additions

# Testing

- [x] Manually tested each block
2026-02-10 19:47:01 +00:00
Jason Larabie 2c8aad8f95 Docs Update for C++ [1/4] (#4118)
# Description of Changes

In order to give reviewers a chance to finish in one session the docs
are getting split up for the C++ update. This pass contains the
following section updates:
- Intro
- Databases
- How To

# API and ABI breaking changes

N/A

# Expected complexity level and risk

1 - Just documentation additions

# Testing

- [x] Manually tested each block
2026-02-10 18:50:46 +00:00
Jason Larabie 52b6c66fa1 Add C++ Bindings (#3544)
# Description of Changes

This adds C++ server bindings (/crate/bindings-cpp) to allow writing C++
20 modules.

- Emscripten WASM build system integration with CMake
- Macro-based code generation (SPACETIMEDB_TABLE, SPACETIMEDB_REDUCER,
etc)
- All SpacetimeDB types supported (primitives, Timestamp, Identity,
Uuid, etc)
- Product types via SPACETIMEDB_STRUCT
- Sum types via SPACETIMEDB_ENUM
- Constraints marked with FIELD* macros

# API and ABI breaking changes

None

# Expected complexity level and risk

2 - Doesn't heavily impact any other areas but is complex macro C++
structure to support a similar developer experience, did have a small
impact on init command

# Testing

- [x] modules/module-test-cpp - heavily tested every reducer
- [x] modules/benchmarks-cpp - tested through the standalone (~6x faster
than C#, ~6x slower than Rust)
- [x] modules/sdk-test-cpp
- [x] modules/sdk-test-procedure-cpp
- [x] modules/sdk-test-view-cpp  
- [x] Wrote several test modules myself
- [x] Quickstart smoketest [Currently in progress]
- [ ] Write Blackholio C++ server module

---------

Signed-off-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: Ryan <r.ekhoff@clockworklabs.io>
Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>
2026-02-07 04:26:45 +00:00
joshua-spacetime 117c7eeb2e [2.0 Breaking] Make connection_id a method on ReducerContext (#4215)
# Description of Changes

Same changes as https://github.com/clockworklabs/SpacetimeDB/pull/4101
but for `connection_id`.

# API and ABI breaking changes

API Breaking

# Expected complexity level and risk

1

# Testing

Pure refactor. Tests and docs have been updated, but no new tests added.
2026-02-06 04:17:36 +00:00