`spacetime.json` config implementation by drogus · Pull Request #4199 · clockworklabs/SpacetimeDB

drogus · 2026-02-04T10:59:53Z

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.

- Add --client-command flag to specify client dev command - Add --server-only flag to skip client execution - Add spacetime.toml config file for project settings - Auto-detect client command from package.json/Cargo.toml/.csproj - Save detected command to spacetime.toml for future runs - Update spacetime init to set default client command - Add spacetime.toml to all templates with appropriate defaults - Update documentation

….com/clockworklabs/SpacetimeDB into feature/spacetime-dev-client-command

- Client environment variables: The dev command now sets SPACETIMEDB_DB_NAME and SPACETIMEDB_HOST environment variables when spawning the client process. This fixes Rust and C# clients which read these env vars to determine which database to connect to. Previously, they would fall back to hardcoded defaults (e.g., quickstart-chat) and fail to connect. - C# module file watching: The file watcher now correctly handles C# modules which have source files directly in spacetimedb/ rather than in spacetimedb/src/. Previously, watching spacetimedb/src/ would fail with "Input watch path is neither a file nor a directory" for C# projects.

# Conflicts: # crates/bindings-typescript/test-app/package.json # templates/react-ts/package.json # templates/svelte-ts/package.json # templates/vue-ts/package.json

…ts and overrides - Replace TypeId/Any type dispatch with serde_json::from_value (fixes u8/num_replicas bug) - Add --no-config flag to publish, generate, and dev commands - Error on empty filter match instead of silent fallback to CLI-only mode - Fix validate() to accept required keys provided via CLI only - Add parent-to-child field inheritance in PublishConfig - Fix dev.rs: consolidate triple config loading, fix process::exit, fix unwraps - Fix include_private to read as bool from config - Add Language serde::Deserialize with aliases for config file support - Add unit tests for inheritance, serde deserialization, and validate

- Remove PublishConfig; SpacetimeConfig IS the database entity with children, generate, and additional_fields (via serde flatten) - Add FlatTarget and LoadedConfig for resolved targets and provenance - Add environment-layered config loading (base > env > local > env.local) - Add --env flag to publish, generate, and dev commands (dev defaults to "dev") - Add database-name glob filtering for publish and generate - Add generate deduplication and generate_entry_specific flag validation - Rename --module-name to --unreal-module-name (with alias for compat) - Add --skip-publish and --skip-generate flags to dev - Add safety prompt in dev when no dev-specific config file is loaded

- Glob filtering: star-matches-all, exact match, multiple wildcards, empty pattern error - Multi-level env layering: staging with base + env + local + env.local overlay order - has_dev_file tracking: false for non-dev envs, true for dev env - dev not propagated to children in FlatTarget fields - Generate dedup with inherited generate from parent (same module-path) - Generate glob filtering and no-match error - iter_all_targets and count_targets - determine_publish_configs: no config, CLI database, config targets, config without database - CLI flag verification: --env default, --skip-publish, --skip-generate

cloutiertyler · 2026-02-14T08:17:47Z

crates/bindings-typescript/test-app/package.json

    "generate": "cargo run -p gen-bindings -- --replacement ../../../src/index && prettier --write src/module_bindings",
    "spacetime:generate": "spacetime generate --lang typescript --out-dir src/module_bindings --project-path server",
-    "spacetime:start": "spacetime start",
+    "spacetime:start": "spacetime start server",


Suggested change

"spacetime:start": "spacetime start server",

"spacetime:start": "spacetime start",

cloutiertyler · 2026-02-14T08:18:01Z

crates/bindings-typescript/test-react-router-app/package.json

    "generate": "cargo run -p gen-bindings -- --replacement ../../../src/index && prettier --write src/module_bindings",
-    "spacetime:generate": "spacetime generate --lang typescript --out-dir src/module_bindings --project-path server",
+    "spacetime:generate": "spacetime generate --lang typescript --out-dir src/module_bindings --module-path server",
    "spacetime:start": "spacetime start server",


Suggested change

"spacetime:start": "spacetime start server",

"spacetime:start": "spacetime start",

cloutiertyler · 2026-02-14T08:24:27Z

crates/cli/src/spacetime_config.rs

+/// Find and load config with environment layering from the current directory.
+///
+/// Loading order (each overlays the previous via top-level key replacement):
+/// 1. `spacetime.json` (required)


Hmm is this really required? If so, should it be?

…n-pattern-d

cloutiertyler · 2026-02-14T08:37:03Z

crates/smoketests/modules/add-remove-index-indexed/src/lib.rs

I'm not sure why there are formatting changes in these. I presume somehow I formatted these and they're not in the above workspace. Should I revert these?

bradleyshep and others added 26 commits January 16, 2026 15:42

Merge branch 'feature/spacetime-dev-client-command' of https://github…

dde2f68

….com/clockworklabs/SpacetimeDB into feature/spacetime-dev-client-command

remove tomls from templates (they are generated automatically)

6012e39

fmt

02307d5

run

dfc4a08

spacetime config -> json

f5ea003

move methods into config

947fb80

Merge branch 'master' into feature/spacetime-dev-client-command

7fe3c04

Update dev.rs

144427a

Update spacetime_config.rs

da2b6cb

docs

9b56f89

update

d995de0

Merge branch 'master' into feature/spacetime-dev-client-command

779cfea

Merge branch 'master' into feature/spacetime-dev-client-command

14528e4

Update LLM benchmark results

97f36da

Bring back eslint entries

710fe98

wip

573d323

Cleanup

827a0b4

Bring back publish after refactoring

54902dc

wip

dac86be

Implement requirements in clap manually

b226c4a

Add display name for languages

693a7c3

Announce what we're doing when using config, remove debug logs

0135fd2

wip

63a26e0

drogus requested review from bfops, cloutiertyler and jdetter as code owners February 4, 2026 10:59

Add more tests for spacetime config

ab95f9f

drogus added 10 commits February 12, 2026 15:37

Rename references to project-path to module-path

86db629

Update docs with --module-path instead of --module-project-path

279d213

Fix gen bindings

5a5e584

Fix lints

1d96c8b

Fix build

e3723b9

Merge remote-tracking branch 'origin/master' into drogus/spacetime-json

4f73f1a

Add includ-private to config's generate

da3ae98

Finish spacetime dev with spacetime.json

5406d75

Regenerate docs

1f1c505

Update CLI reference

321629a

drogus force-pushed the drogus/spacetime-json branch from 02f4afa to 321629a Compare February 12, 2026 20:28

drogus and others added 7 commits February 12, 2026 22:20

Fix tests

177f3e7

Fix smoketests

26ae014

Merge remote-tracking branch 'origin/master' into drogus/spacetime-json

7e390e1

Fix generate and publish smoketests

50347d4

Improve error message for module specific args

2fec1a0

Check for module specific args in generate

0fdf4a1

Merge remote-tracking branch 'origin/master' into drogus/spacetime-json

bd99342

# Conflicts: # crates/bindings-typescript/test-app/package.json # templates/react-ts/package.json # templates/svelte-ts/package.json # templates/vue-ts/package.json

cloutiertyler enabled auto-merge February 13, 2026 15:00

cloutiertyler added 4 commits February 14, 2026 00:03

Run cargo fmt

7ef25a4

cloutiertyler reviewed Feb 14, 2026

View reviewed changes

cloutiertyler added 3 commits February 14, 2026 03:32

Fix exec_ex call in testing crate: add missing pre_loaded_config arg

36cdc30

Update docs: rename --module-name to --unreal-module-name

7d927c1

Merge remote-tracking branch 'origin/master' into tyler/spacetime-jso…

da8dd39

…n-pattern-d

cloutiertyler reviewed Feb 14, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

`spacetime.json` config implementation#4199

`spacetime.json` config implementation#4199
drogus wants to merge 72 commits intomasterfrom
drogus/spacetime-json

drogus commented Feb 4, 2026

Uh oh!

cloutiertyler Feb 14, 2026

Uh oh!

cloutiertyler Feb 14, 2026

Uh oh!

cloutiertyler Feb 14, 2026

Uh oh!

cloutiertyler Feb 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	"spacetime:start": "spacetime start server",
	"spacetime:start": "spacetime start",

Conversation

drogus commented Feb 4, 2026

Description of Changes

API and ABI breaking changes

Expected complexity level and risk

Testing

Uh oh!

cloutiertyler Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

cloutiertyler Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

cloutiertyler Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

cloutiertyler Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants