# Description of Changes
We apparently have stale usage of `--project-path` in a ton of our
templates. This was renamed to `module-path` a while ago, but it looks
like that was only partially fixed in templates.
# API and ABI breaking changes
None
# Expected complexity level and risk
1
# Testing
I don't think it's _more_ broken 🤷
---------
Signed-off-by: Zeke Foppa <196249+bfops@users.noreply.github.com>
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
This pull request updates the template system to support richer metadata
and improves the interactive CLI experience for selecting templates. The
main changes are the addition of a `client_framework` field to template
metadata, a refactor of the templates JSON generation and parsing, and a
redesign of the interactive template selection flow to group templates
by language/framework and use fuzzy search for easier navigation.
<img width="407" height="409" alt="image"
src="https://github.com/user-attachments/assets/d3548505-80e8-4778-8bfb-71d5e3fe31e9"
/>
**Template Metadata and Serialization Improvements:**
* Added a new `client_framework` field to all template metadata files
(e.g., `.template.json`) and updated the Rust structs (`TemplateInfo`,
`TemplateDefinition`, etc.) to support this field, enabling more
descriptive and flexible template selection.
[[1]](diffhunk://#diff-5438edbe7b41e3e0a1a62ce0ebde2a833a0441d76c6ffdf16093a3cff258f462R3)
[[2]](diffhunk://#diff-34a44755a07373e9c2872db87a64c3fd752cfee7d8d536045909daf861ea4728R3)
[[3]](diffhunk://#diff-a826c5a2eac977cff44022d72856ec4b1af176ffbb50697f22857e1e3d478aa1R3)
[[4]](diffhunk://#diff-7a21474fbc5bbbd989e89f32aa8dcc25fcc6fe4ac43d418c42b2b38603d21714R3)
[[5]](diffhunk://#diff-d8ee9fd0ef15ed23f0f7f38e556d789bdefc6c37dab67fbfccebc513b9da871cR3)
[[6]](diffhunk://#diff-7224fd4300f9c5af7834ff5989a76a399ce9117c28f5d7e2c1fbd6bdaf45be1bR3)
[[7]](diffhunk://#diff-8b015b0ce6339c444ef5ef4dc5e862275d98967e5c189da37b51bdaa58443606R3)
[[8]](diffhunk://#diff-89e32f7fc9fc42863998d7651bc7fa1fdfb352e8ac3ef45792e3f1374052c9ddR3)
[[9]](diffhunk://#diff-8259d300fda149c968a68989aec2bc2afa479aded649ac6b8d3c4b277f610542R3)
[[10]](diffhunk://#diff-bb8b9202e51fb7038efa2f2bb23872afa02caf71ab3a0fb7f513ca7822c1b8faR3)
[[11]](diffhunk://#diff-18497b72a2306fc2560475e2548cfe1b96b6206c395380437ba1fafefd66e126L199-R221)
[[12]](diffhunk://#diff-18497b72a2306fc2560475e2548cfe1b96b6206c395380437ba1fafefd66e126R279)
* Refactored the templates JSON generation to use `serde` for
serialization, replacing manual string building, and ensured that
optional string fields serialize as empty strings when not present.
**CLI Interactive Template Selection Redesign:**
* Removed the previous "highlights" concept and reworked the interactive
selection to group templates by language/framework combinations, showing
counts and using fuzzy search for easier filtering.
[[1]](diffhunk://#diff-7fcfe09d0f54dde6b2fc0cb2b9ff02ab064add692f5602d6f627fe3840e282caL38-L48)
[[2]](diffhunk://#diff-7fcfe09d0f54dde6b2fc0cb2b9ff02ab064add692f5602d6f627fe3840e282caL772-R833)
[[3]](diffhunk://#diff-7fcfe09d0f54dde6b2fc0cb2b9ff02ab064add692f5602d6f627fe3840e282caL813-L850)
* Updated the selection menus to allow users to pick a
language/framework group, then choose from multiple templates if
available, or opt to clone from GitHub or select "None."
[[1]](diffhunk://#diff-7fcfe09d0f54dde6b2fc0cb2b9ff02ab064add692f5602d6f627fe3840e282caL772-R833)
[[2]](diffhunk://#diff-7fcfe09d0f54dde6b2fc0cb2b9ff02ab064add692f5602d6f627fe3840e282caL813-L850)
* Improved language label formatting for better user experience in the
CLI prompt.
**Codebase Cleanup and API Changes:**
* Removed unused highlight-related structs and logic from the CLI,
simplifying the template fetching API to return only templates.
[[1]](diffhunk://#diff-7fcfe09d0f54dde6b2fc0cb2b9ff02ab064add692f5602d6f627fe3840e282caL38-L48)
[[2]](diffhunk://#diff-7fcfe09d0f54dde6b2fc0cb2b9ff02ab064add692f5602d6f627fe3840e282caL198-R198)
* Updated all template selection logic to use the new API and data
structures.
[[1]](diffhunk://#diff-7fcfe09d0f54dde6b2fc0cb2b9ff02ab064add692f5602d6f627fe3840e282caL683-R679)
[[2]](diffhunk://#diff-7fcfe09d0f54dde6b2fc0cb2b9ff02ab064add692f5602d6f627fe3840e282caL748-R744)
These changes make template selection more intuitive and scalable as
more templates and frameworks are added.
---------
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
## Summary
Multiple fixes and improvements to `spacetime dev`, `spacetime publish`,
`spacetime init`, and templates:
### CLI fixes
- **Fix `spacetime dev` watch path and .env.local handling** for
templates with a `spacetimedb/` subdirectory
- **Validate package manager availability** before installing
dependencies — re-prompts if the selected PM isn't on PATH
- **Remove JS/TS beta warning** from `spacetime publish`
- **Remove unstable warning** from `spacetime init`
- **Remove unused `spacetime energy` command** (can be re-added later
when properly implemented)
- **Fix `tsc` detection on Windows** — `set_extension(".cmd")` produced
`tsc..cmd` (double dot); fixed to `set_extension("cmd")`
- **Add `typescript` as devDependency** to all server template
`spacetimedb/package.json` files so `tsc` is available during build
- **Strip `\?\` extended-length path prefix** from user-facing output in
both `dev` and `publish` commands (produced by `fs::canonicalize()` on
Windows)
- **Fix publish reporting success when user declines** non-local server
prompt — changed `return Ok(())` to `bail!()` consistent with other
abort cases
- **Forward stdin to client process** in `spacetime dev` so interactive
CLI templates work
### Template fixes
- **Fix Angular template environment variables** — Angular's esbuild
builder doesn't support `import.meta.env`, so we use a dev script to
generate `environment.local.ts` with Angular's native `fileReplacements`
pattern
- **Fix TanStack Start template** — rename `createRouter` to `getRouter`
(v1.121+ breaking change), upgrade to React 19, and add
`@vitejs/plugin-react` for automatic JSX runtime support
- **Fix `moduleResolution` in remix-ts and nextjs-ts** server tsconfigs
— change from `"node"` to `"bundler"` to support subpath exports like
`spacetimedb/server`
- **Fix browser-ts template** — convert from static HTML + IIFE bundle
to standard Vite dev server app so it works with `spacetime dev` and
reads env vars from `.env.local`
- **Add `deno` as devDependency** to deno-ts template (matches how
bun-ts includes bun)
- **Convert basic-ts from empty web app to CLI app** matching basic-rs —
connect, subscribe to person table, print on insert
## Test plan
- [x] `cargo test -p spacetimedb-cli` — all 133 tests pass
- [ ] `spacetime dev --template angular-ts` — verify Angular app
connects with correct database name
- [ ] `spacetime dev --template react-ts` — verify React template still
works
- [ ] `spacetime dev --template tanstack-ts` — verify TanStack Start
template loads without errors
- [ ] `spacetime dev --template remix-ts` — verify Remix template builds
and runs
- [ ] `spacetime dev --template nextjs-ts` — verify Next.js template
still works
- [ ] `spacetime dev --template browser-ts` — verify Vite dev server
starts and app connects
- [ ] `spacetime dev --template bun-ts` — verify Bun CLI template runs
interactively
- [ ] `spacetime dev --template basic-ts` — verify CLI connects and
prints on insert
- [ ] Verify no `\?\` prefix in any displayed paths on Windows
- [ ] Verify no `tsc not found` warning when building server modules
- [ ] Select unavailable package manager at init prompt — verify
re-prompt
- [ ] Decline non-local server prompt — verify clean error instead of
"Published successfully!"
---------
Co-authored-by: Piotr Sarnacki <drogus@gmail.com>
Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <bot@clockworklabs.com>
# Description of Changes
`spacetime build` now attempts to run tsc for typescript modules, and
will emit a warning if it's not present. This PR makes it so our CLI
stops emitting a warning for our templates.
# Expected complexity level and risk
1
# Testing
- [x] Verified that typescript gets properly installed.
# Description of Changes
- Quickstart templates: use workspace:* for spacetimedb instead of 1.*
so in-repo dev uses the local SDK.
# API and ABI breaking changes
None.
# Expected complexity level and risk
1. Template and workspace config only.
# Testing
- [ ] `pnpm install` from repo root; `spacetime dev --no-config` from a
template.
- [ ] `spacetime init` in a new dir; generated project has versioned
`spacetimedb`, not `workspace:*`.
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
# Description of Changes
This adds some logging utilities, that will probably be helpful for
debugging issues. `stdbLogger` can now accept lazy messages. If you call
`setGlobalLogLevel`, that will set a log level globally. It is set to
`info` by default, but when troubleshooting, we can ask people to run
`setGlobalLogLevel('trace')` and share more detailed logs.
In this PR, it adds a new new logs at the `trace` level:
- All outgoing messages to the server
- All incoming messages from the server
- After handling a server message, we log the number of triggered row
callbacks
There are also some formatting niceties to truncate large arrays and
redact fields that look like credentials.
We are also using `safe-stable-stringify` to handle some cases that
would be errors in `JSON.stringify`.
# API and ABI breaking changes
This adds the `setGlobalLogLevel` function, which is useful for
debugging.
# Expected complexity level and risk
1.5 - the only real risk here is that
# Testing
This has some tests of formatting in `logger.test.ts`.
# Description of Changes
All types are now defined and exported in `module_bindings/types.ts`,
meanings there's only one module you need to import from to access
types.
# Expected complexity level and risk
2
# Testing
n/a, no change in behavior.
# Description of Changes
This fixes a couple issues:
- We are now using the `SendDroppedRows` flag for unsubscribe messages.
- We parse reducer errors as strings now when throwing errors.
- `useTable` was not doing client-side filtering correctly for object
types (Timestamp, ConnectionId, Identity)
- `useTable` was not always recomputing snapshots when it needed to,
because it couldn't distinguish between two events if they were caused
by reducers called by other connections (or two subscription applied
events). All events how have a client-generated id attached, so we can
tell if there was actually a new event processed.
Once we have per-query storage, we can purge the client-side filtering
code.
This also adds some tests to cover these cases, and includes a bit of
refactoring.
Another change added here is to use `SenderError` in the typescript SDK
for errors that were returned by reducers (which throw `SenderError` in
typescript modules).
# Expected complexity level and risk
1
# Testing
This has some new tests added.
Much of the `useTable` logic was tested manually.
# 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>
## 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>
# 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>
# 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. -->
# 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
# Description of Changes
This update the typescript sdk to use the v2 protocol.
The main user-facing API change is removing the existing reducer
callbacks, and instead having reducers return a `Promise`.
# API and ABI breaking changes
The reducer functions `conn.reducers.onX` and `conn.reducers.removeOnX`
no longer exist, and reducers now return `Promise<void>`.
# Expected complexity level and risk
2.5.
# Testing
This has mostly been tested manually. I'm still updating some of the
unit tests (I commented out the ones that used reducer callbacks).
---------
Co-authored-by: Phoebe Goldman <phoebe@goldman-tribe.org>
Co-authored-by: = <cloutiertyler@gmail.com>
# 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
# 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. -->
NOTE: Cherry-picking
https://github.com/clockworklabs/SpacetimeDB/pull/4127 from the
`2.0-breaking-changes` branch.
## Original PR Description
This changes generated types in ts client bindings. We currently
generate a few different types of types: reducer args, procedure args,
rows, and user defined types. To avoid potential conflicts between these
types (for example, if a user defined a type called `FooRow`, and also
had a tabled named `foo`, we would end up with two types named
`FooRow`), this puts each set of types in a different file and
namespace. We also stopped exporting the `xxxRow` types, because there
is always another type generated for those. We now have a `types`
directory, which has an `index.ts` with user defined types, along with
`reducers.ts` and `procedures.ts` for the types generated for
reducer/procedure parameters.
```
import type * as Types from './module_bindings/types';
var currentMessages: Types.Message[] = [];
```
or
```
import { type Message } from './module_bindings/types';
var currentMessages: Message[] = [];
```
This has a couple other changes:
- For procedure and reducer types, this adds a suffix of `Args`, since
we may want types for the return values in the future.
- For all of the types, instead of exposing the schema object, we are
now giving the typescript type (e.g. `export type Message =
__Infer<typeof MessageRow>;`). I couldn't think of a reason for users to
want the schema object, so this should save users from needing to do all
of the `Infer` boilerplate.
This is a breaking change for v2.
2. This only changes typescript, and it should generally make thing
easier to use.
---------
Co-authored-by: Jeffrey Dallatezza <jeffreydallatezza@gmail.com>
# Description of Changes
This PR renames the templates to always use shorthand for the language,
specify a framework (or console) if necessary, and shorten the naming in
general
# Expected complexity level and risk
1
# Testing
I've tested generating templates manually
---------
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Zeke Foppa