clockworklabs / clockworklabs/SpacetimeDB

Confusing error messages when TypeScript project is not properly initialized

Open
#4,476 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
25.2k
Forks
1.1k
Avg merge
2d 7h
Merged PRs (30d)
46

Description

Description

When running spacetime dev in a directory with spacetime.json but without a properly initialized TypeScript project, the error messages are confusing and don't guide users to the root cause.

Steps to Reproduce

  1. Create a directory with spacetime.json and spacetime.local.json:
// spacetime.json
{
  "server": "maincloud"
}

// spacetime.local.json
{
  "database": "test-db"
}
  1. Have a package.json present (either symlinked or for a different project) that doesn't include TypeScript as a dependency

  2. Do NOT have a tsconfig.json file

  3. Run spacetime dev <database-name>

Actual Behavior

The CLI outputs:

Found existing SpacetimeDB project.
...
Building...
tsc not found in node_modules. Make sure you have the `typescript` package as a dev-dependency and that your dependencies are installed.
Error: Failed to build project

Caused by:
    Something went wrong inside rolldown, please report this problem at https://github.com/rolldown/rolldown/issues.
    Tsconfig not found /home/user/tsconfig.json
    
    Caused by:
        Failed to resolve `tsconfig` option: /home/user/tsconfig.json

Expected Behavior

The CLI should:

  1. Validate project structure - Don't just check for spacetime.json to determine if a project exists. Validate that the project is properly initialized with:

    • Correct package.json with required dependencies
    • tsconfig.json for TypeScript projects
    • The spacetimedb/ directory with module code
  2. Provide actionable error messages - Instead of a cryptic rolldown error, show:

    Error: TypeScript project not properly initialized
    
    Missing or invalid files:
    - tsconfig.json not found
    - TypeScript dependency not installed
    - spacetimedb/ module directory not found
    
    To fix this, run:
    spacetime init --lang typescript <project-name>
    
  3. Detect incomplete initialization - When spacetime.json exists but other required files don't, warn the user:

    Warning: Found spacetime.json but project appears incomplete.
    Did you mean to run 'spacetime init --lang typescript'?
    

Environment

  • SpacetimeDB CLI version: 2.0.1
  • OS: Linux
  • Node.js version: v22.20.0

Additional Context

This issue affects developer experience, especially for new users trying to set up SpacetimeDB projects. The current error message:

  1. Incorrectly states "Found existing SpacetimeDB project" when the project isn't properly set up
  2. Points to a rolldown GitHub issues page instead of helping users fix their setup
  3. Doesn't mention that spacetime init should be used to properly initialize a project

Suggested Fix

Add validation in the CLI before attempting to build:

// Pseudocode
fn validate_typescript_project(project_path: &Path) -> Result<(), Error> {
    if !project_path.join("tsconfig.json").exists() {
        return Err(Error::MissingTsConfig {
            suggestion: "Run 'spacetime init --lang typescript' to create a new project"
        });
    }
    
    if !typescript_installed(project_path) {
        return Err(Error::MissingTypeScript {
            suggestion: "Install TypeScript with: npm install --save-dev typescript"
        });
    }
    
    if !project_path.join("spacetimedb").exists() {
        return Err(Error::MissingModuleDirectory {
            suggestion: "Create a spacetimedb/ directory with your server module code"
        });
    }
    
    Ok(())
}

Labels

  • bug
  • developer-experience
  • cli
  • typescript

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the spacetime dev project-detection and TypeScript build flow, then compare it with spacetime init --lang typescript. Add validation for the required project files and dependencies before building, with actionable incomplete-project errors; done means the reported setup problems no longer fall through to the rolldown error.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust, typescript
Domain
cli, developer-experience
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.