feat: add create-spacetime CLI tool #3251

clockwork-tien · 2025-09-17T13:27:20Z

Description of Changes

Introduce CLI tool for scaffolding SpacetimeDB projects and create applications with React frontends and Rust or C# backends
Add templates/create-spacetime/ with complete CLI implementation which supports interactive project creation, package manager detection, and deployment options (Maincloud and local deployment)
Update pnpm-workspace.yaml to include new package
Detailed package description and usage examples provided in templates/create-spacetime/README.md

Screenshots

Run CLI tool using npm create spacetime@latest

Testing

Package builds successfully (pnpm run build within templates/create-spacetime) and runs without errors (pnpm run test)
CLI creates projects with interactive prompts, which support both Rust and C# templates with React and deployment options for local or Maincloud

egormanga · 2025-09-18T11:54:55Z

My two cents:
I'd call it spacetime-create instead, as it'll be easier to comprehend in terms of namespaces, and to tab-complete when you forgot the second word (otherwise there's nothing to complete if it comes first).

…into tien/feat/create-spacetime

cloutiertyler · 2025-09-24T03:46:24Z

My two cents: I'd call it spacetime-create instead, as it'll be easier to comprehend in terms of namespaces, and to tab-complete when you forgot the second word (otherwise there's nothing to complete if it comes first).

npm create is an npm command, we don't have control over that

templates/create-spacetime/.eslintrc.json

cloutiertyler · 2025-09-24T03:54:19Z

templates/create-spacetime/src/index.ts

+    console.log();
+  }
+
+  if (options.template && !isValidTemplate(options.template)) {


Would it be possible to modify the script so that if it's not in the list of built in templates, it tries to clone the template from GitHub?

Thank you, I have updated to add support/option for non built-in templates.

cloutiertyler

This is looking really really good. I just left one more request about downloading templates from GitHub if the user specifies one that we don't know about.

Also as a minor nit, create-spacetime itself is not really a template, so it probably shouldn't go in the templates directory. I would imagine the templates directory is where we store/host all the built in templates.

…se eslint.config.js format

…into tien/feat/create-spacetime

egormanga · 2025-09-24T13:16:07Z

@cloutiertyler Oh, I see now. Thought you were making a standalone scaffolding binary called that. Alright then!

clockwork-tien · 2025-09-24T13:36:13Z

@cloutiertyler Thank you for the review! I have updated to rely on root eslint.config.js instead, implemented support/option for non built-in templates, moved create-spacetime from templates folder to cli folder, and published new version.

cli/create-spacetime/src/constants.ts

cloutiertyler · 2025-09-25T02:56:07Z

cli/create-spacetime/src/constants.ts

+
+export const SPACETIME_VERSIONS = {
+  SDK: "^1.3.1",
+  RUNTIME: "1.3.*",


This doesn't appear to be used anywhere.

Thank you, I removed this unused variable.

cloutiertyler · 2025-09-25T03:08:29Z

npm-packages/create-spacetime/src/index.ts

+    process.exit(1);
+  }
+
+  if (!deps.spacetime) {


Is there a reason we couldn't just install this for them? Obviously we'd ask them first, but then we could just run the appropriate install script based on the platform.

Eventually I think we'd like to move most of this functionality directly into the spacetime cli command, so it would make sense that this actually just becomes a simple bootstrapping TypeScript script to install the CLI and then run a command like:

spacetime init --template foobar/baz

Ah I could do it as well 👍 . Initially I had a version for that but held back due to cross-platform complexity.

cloutiertyler · 2025-09-25T03:11:49Z

npm-packages/create-spacetime/tsconfig.json

Could you rename cli to npm-packages instead? Sorry for the back and forth on this.

Yes I renamed cli to npm-packages 👍

cloutiertyler · 2025-09-25T03:25:51Z

npm-packages/create-spacetime/src/lib/create-project.ts

+      content = content.replace(/log\.workspace = true/g, 'log = "0.4"');
+      content = content.replace(
+        /spacetimedb = \{ path = ".*" \}/g,
+        `spacetimedb = "${SPACETIME_VERSIONS.CLI}"`,


Why are we changing the version here at all? Shouldn't this version be specified in the template?

Additionally, this is not the CLI version. We typically call this version the "module library version". Arguably it should be whatever is in the template, or arguably it could be the wildcard version, although that would cause templates to break silently if we push breaking changes.

The template uses a relative path spacetimedb = { path = "../../crates/bindings" } instead of a published version, this path doesn't exist when cloning outside the SpacetimeDB monorepo, so I needed to update with a fixed version.

cloutiertyler · 2025-09-25T03:26:48Z

npm-packages/create-spacetime/src/lib/create-project.ts

+    clientPackage.name = `${name}-client`;
+
+    if (clientPackage.dependencies?.[SPACETIME_SDK_PACKAGE]) {
+      clientPackage.dependencies[SPACETIME_SDK_PACKAGE] = SPACETIME_VERSIONS.SDK;


I'm also not sure why we're editing the template to add our own version in here as well. I guess to get them on the most up to date version?

The template has "spacetimedb": "workspace:*" in package.json, which didn't work when cloning standalone version so I needed to update with a fixed version.

cloutiertyler

I'm having the terrible realization that most of this code should really exist within spacetime init and be written in Rust. That way people who don't want to execute npm or npx can still use the template creator.

This tool would then become a thin wrapper which would essentially just install spacetime if it was not there and then execute spacetime init --template.

Co-authored-by: Tyler Cloutier <[email protected]> Signed-off-by: clockwork-tien <[email protected]>

…pacetimedb package

feat: create-spacetime command and package

461e353

clockwork-tien requested a review from cloutiertyler September 17, 2025 13:27

clockwork-tien changed the title ~~feat: create-spacetime command and package~~ feat: add create-spacetime CLI tool Sep 17, 2025

feat(create-spacetime): general improvements and refactor

6477062

clockwork-tien added 2 commits September 19, 2025 21:30

feat(create-spacetime): deployment config improvements, code refactor

17b926e

Merge branch 'master' of https://github.com/clockworklabs/SpacetimeDB …

b41dbb1

…into tien/feat/create-spacetime

bfops added the release-any To be landed in any release window label Sep 22, 2025

cloutiertyler reviewed Sep 24, 2025

View reviewed changes

templates/create-spacetime/.eslintrc.json Outdated Show resolved Hide resolved

cloutiertyler reviewed Sep 24, 2025

View reviewed changes

clockwork-tien added 2 commits September 24, 2025 16:03

feat(create-spacetime): custom template option, move to cli folder, u…

c562563

…se eslint.config.js format

Merge branch 'master' of https://github.com/clockworklabs/SpacetimeDB …

e9bb472

…into tien/feat/create-spacetime

feat(create-spacetime): update to use root eslint.config.js

8f7aa3a

clockwork-tien requested a review from cloutiertyler September 24, 2025 13:39

cloutiertyler reviewed Sep 25, 2025

View reviewed changes

cli/create-spacetime/src/constants.ts Outdated Show resolved Hide resolved

cloutiertyler reviewed Sep 25, 2025

View reviewed changes

clockwork-tien and others added 3 commits September 25, 2025 13:30

Update cli/create-spacetime/src/constants.ts

7949bea

Co-authored-by: Tyler Cloutier <[email protected]> Signed-off-by: clockwork-tien <[email protected]>

feat(create-spacetime): move to npm-packages folder, updates to use s…

818f964

…pacetimedb package

chore(create-spacetime): update SPACETIME_VERSIONS var namings

8c8bc38

feat: add create-spacetime CLI tool #3251

Are you sure you want to change the base?

feat: add create-spacetime CLI tool #3251

Uh oh!

Conversation

clockwork-tien commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of Changes

Screenshots

Testing

Uh oh!

egormanga commented Sep 18, 2025

Uh oh!

cloutiertyler commented Sep 24, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cloutiertyler left a comment

Choose a reason for hiding this comment

Uh oh!

egormanga commented Sep 24, 2025

Uh oh!

clockwork-tien commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cloutiertyler Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cloutiertyler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

clockwork-tien commented Sep 17, 2025 •

edited

Loading

clockwork-tien commented Sep 24, 2025 •

edited

Loading

cloutiertyler Sep 25, 2025 •

edited

Loading