SpacetimeDB/templates/hangman-react-ts

Get a competitive SpacetimeDB Hangman game running with React and TypeScript.

Prerequisites

• Node.js 18+ installed
• SpacetimeDB CLI installed

Install the SpacetimeDB CLI before continuing.

---

Create your project

Run the spacetime dev command to create a new project with a TypeScript SpacetimeDB module and React client.

This will start the local SpacetimeDB server, publish your module, generate TypeScript bindings, and start the React development server.

spacetime dev --template hangman-react-ts

Open your app

Navigate to http://localhost:5173 to play Hangman.

Every player guesses the same hidden word on a private board. A round lasts 60 seconds, followed by 10 seconds of revealed results and rankings.

Explore the project structure

Your project contains both server and client code.

Edit spacetimedb/src/index.ts to change game rules or the word list. Edit src/App.tsx to change the game interface.

my-spacetime-app/
├── spacetimedb/          # Your SpacetimeDB module
│   └── src/
│       └── index.ts      # Game tables, reducers, and round transitions
├── src/                  # React frontend
│   ├── App.tsx
│   └── module_bindings/  # Auto-generated types
└── package.json

Understand tables and reducers

Open spacetimedb/src/index.ts to see the module code. The template includes public round and result tables, private player progress, and scheduled round transitions. The set_name reducer registers a nickname and guess_letter submits one letter for the current round.

Tables store game state. Reducers are functions that modify data - they are the only way to write to the database.

export const set_name = spacetimedb.reducer(
  { name: t.string() },
  (ctx, { name }) => {
    const trimmedName = name.trim();
    if (trimmedName.length === 0 || trimmedName.length > 20) {
      throw new SenderError('Names must be between 1 and 20 characters');
    }

    const existing = ctx.db.player.identity.find(ctx.sender);
    if (existing) {
      ctx.db.player.identity.update({ ...existing, name: trimmedName });
    } else {
      ctx.db.player.insert({ identity: ctx.sender, name: trimmedName });
    }
  }
);

export const guess_letter = spacetimedb.reducer(
  { letter: t.string() },
  (ctx, { letter }) => {
    const guess = letter.trim().toUpperCase();
    if (!/^[A-Z]$/.test(guess)) {
      throw new SenderError('Guess one letter from A to Z');
    }

    // Update this player's private progress for the active round.
  }
);

Test with the CLI

Open a new terminal and navigate to your project directory. Then use the SpacetimeDB CLI to join a round, guess letters, and inspect your state.

cd my-spacetime-app

# Pick a nickname before guessing
spacetime call set_name '"Ada"'

# Guess one letter
spacetime call guess_letter '"A"'

# Inspect the active public round and your private board view
spacetime sql "SELECT * FROM current_round"
spacetime sql "SELECT * FROM my_progress"

Understand round state and privacy

The module runs one shared competitive round at a time:

• current_round publishes the timer, difficulty, and word length. It reveals the answer only during results.
• my_progress exposes each player only to their own masked word and guesses during an active round.
• round_result publishes the completed round standings once the timer ends.
• transition_timer schedules the results phase and the start of the next round.

Customize the game

The built-in word list and round durations are at the top of spacetimedb/src/index.ts. Add words, adjust difficulty labels, or change the active and results durations there.

The React UI in src/App.tsx includes the gallows drawing, masked-word board, keyboard, timer, nickname form, and standings panel. Edit those components and src/App.css to change how the game looks and plays.

Next steps

• Read the TypeScript SDK Reference for detailed API docs
• See the Chat App Tutorial for another complete React example