document the quick start path using a local db instead of maincloud

[DefinitelyMaybe]

Hey there,

so quick start guide works as expected when publishing to maincloud.spacetimedb.com . The problem is that trying to run things locally aint so smooth.

I haven't managed to get a anything working yet even with lots of help from the community discord

Happy if i just missed a page somewhere already in the docs.

[bfops]

Hey @DefinitelyMaybe! Sorry that the quickstart has been giving you a hard time.

In principle, local servers should be pretty similar to maincloud - just a different IP address and -s/--server param on the commands. What's the issue you're currently having? Is the vite server still having issues? What's the error?

[DefinitelyMaybe]

ok, so in theory, i could just change one of the commands on the quickstart page and it'd work?

PS C:\Users\blah\Documents\test> spacetime dev --template svelte-ts
No SpacetimeDB project found in current directory.
Would you like to initialize a new project? yes
You are logged in to SpacetimeDB.
✔ Project name · app
✔ Project path · ./app
✔ Database name · app-bhliz
Template: svelte-ts
Initializing project from template...
Setting up client (typescript)...
✅ Wrote environment configuration to ./app\.env.local
Note: Run 'npm install' in the project directory to install dependencies
Setting up server (typescript)...
Project initialized successfully!
✓ Created ./app\spacetime.json

TypeScript server requires dependencies to be installed before publishing.
✔ Which package manager would you like to use? · npm
Installing dependencies with npm...

added 10 packages in 19s
Dependencies installed successfully!
Installing dependencies with npm...

added 55 packages in 14s
Dependencies installed successfully!
✓ Created ./app\spacetime.local.json

Tip: To interact with your database, open a new terminal and run:
  cd ./app
  spacetime call add Alice
  spacetime sql "SELECT * FROM person"
  spacetime logs

✓ Using configuration from C:\Users\blah\Documents\test\app\spacetime.json, C:\Users\blah\Documents\test\app\spacetime.local.json
✓ Detected client command and saved to C:\Users\blah\Documents\test\app\spacetime.json

Starting development mode...
Database: app-bhliz
Watching for changes in: C:\Users\blah\Documents\test\app\spacetimedb
Client command: npm run dev
Press Ctrl+C to stop

Building...
Build complete!
Updating .env.local with database name app-bhliz...
No generate targets in spacetime.json. Skipping module bindings generation.   
Publishing...
Publishing module C:\Users\blah\Documents\test\app\spacetimedb to database 'app-bhliz'
Build finished successfully.
You are about to publish to a non-local server: maincloud.spacetimedb.com
Are you sure you want to proceed? [y/N]
Error: Publish aborted by user.

Cause right now the error is that i aborted because i didn't publish to maincloud 🤷‍♂️ Not even a hint as to what the next steps should be to setup something local, which was the default N

[bfops]

It should work if you run with spacetime dev --server local instead of just spacetime dev. (Note that you'll need to have a local server already running with spacetime start).

[DefinitelyMaybe]

thank goodness. that worked.

for future peoples reading, including the template just another arg spacetime dev --template svelte-ts --server local

[DefinitelyMaybe]

quick addition to this, I think the spacetime:publish:local npm task needs to be updated.

Executing task: npm run spacetime:publish:local 


> app@0.0.1 spacetime:publish:local
> spacetime publish --project-path spacetimedb --server local

error: unexpected argument '--project-path' found

  tip: to pass '--project-path' as a value, use '-- --project-path'

Usage: spacetimedb-cli.exe publish [OPTIONS] [name|identity]

For more information, try '--help'.

 *  The terminal process "C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe -Command npm run spacetime:publish:local" terminated with exit code: 1.

[bfops]

Good catch, thank you! That's just a bug. I opened a PR here: #4564

[mikiadev]

I'm having the same struggle when trying to test, nowhere in the quickstart guide for Svelte it says about the --server local or having the server running with spacetime start. However then it errors:

mika@redrix ⚡➜ ~/git spacetime dev --template svelte-ts --server local
No SpacetimeDB project found in current directory.
Would you like to initialize a new project? yes
✔ Project name · space
✔ Project path · ./space
✔ Database name · space-bavzn
Template: svelte-ts
Initializing project from template...
Setting up client (typescript)...
✅ Wrote environment configuration to ./space/.env.local
Note: Run 'npm install' in the project directory to install dependencies
Setting up server (typescript)...
Project initialized successfully!
✓ Created ./space/spacetime.json

TypeScript server requires dependencies to be installed before publishing.
✔ Which package manager would you like to use? · bun
Installing dependencies with bun...
bun install v1.3.9 (cf6cdbbb)

+ typescript@5.6.3 (v5.9.3 available)
+ spacetimedb@2.0.3

10 packages installed [816.00ms]
Dependencies installed successfully!
Installing dependencies with bun...
[0.03ms] ".env.local"
bun install v1.3.9 (cf6cdbbb)

+ @sveltejs/vite-plugin-svelte@5.1.1 (v6.2.4 available)
+ svelte@5.53.7
+ svelte-check@4.4.4
+ typescript@5.6.3 (v5.9.3 available)
+ vite@6.4.1 (v7.3.1 available)
+ spacetimedb@2.0.3

55 packages installed [1410.00ms]
Dependencies installed successfully!
✓ Created ./space/spacetime.local.json

Tip: To interact with your database, open a new terminal and run:
  cd ./space
  spacetime call add Alice
  spacetime sql "SELECT * FROM person"
  spacetime logs

✓ Using configuration from /home/mika/git/space/spacetime.json, /home/mika/git/space/spacetime.local.json
✓ Detected client command and saved to /home/mika/git/space/spacetime.json

Starting development mode...
Database: space-bavzn
Watching for changes in: /home/mika/git/space/spacetimedb
Client command: bun run dev
Press Ctrl+C to stop

Building...
Build complete!
Updating .env.local with database name space-bavzn...
No generate targets in spacetime.json. Skipping module bindings generation.
Publishing...
Publishing module /home/mika/git/space/spacetimedb to database 'space-bavzn'
Build finished successfully.
Uploading to local => http://127.0.0.1:3000
Checking for breaking changes...
Error: Pre-publish check failed with status 401 Unauthorized: TokenError(Error(InvalidSignature))

[DefinitelyMaybe]

@mikiadev that error looks like a login issue. Try spacetime logout then login again spacetime login