Spectrum

A real-time multiplayer word association game built with PartyKit, React, and TypeScript. Features clean hexagonal architecture with shared game logic between client and server.

Quick Start

# Install dependencies
pnpm install

# Start all development servers (web app + PartyKit server)
pnpm dev

Then open http://localhost:3000 in multiple browser tabs/windows to play Spectrum with real-time multiplayer!

Development Scripts

• pnpm dev - Start all apps (web + server)
• pnpm dev:web-next - Start only the web app
• pnpm dev:server-partykit - Start only the PartyKit server
• pnpm build - Build all apps
• pnpm build:web-next - Build only the web app
• pnpm build:server-partykit - Deploy the PartyKit server

Architecture

This monorepo follows hexagonal architecture principles.

Packages

Package	Description
@repo/game-protocol	Shared types and events.
@repo/game-ports	Port interfaces + adapters (BroadcastTransport).
@repo/game-core	Pure logic: applyEvent, createInitialState.
@repo/web-next	Next.js 16 web app.

Packages export TypeScript source directly — no build step needed. Next.js compiles everything via transpilePackages.

Project Structure

spectrum/
├── apps/
│   └── web-next/           # Next.js app
│       └── app/page.tsx    # Counter UI
├── packages/
│   ├── game-protocol/      # Types & events
│   ├── game-ports/         # Port interfaces + adapters
│   └── game-core/          # Business logic
├── package.json
├── pnpm-workspace.yaml
└── tsconfig.base.json

Scripts

Command	Description
pnpm dev	Start Next.js development server
pnpm build	Build the web app for production
pnpm lint	Run ESLint across all packages
pnpm format	Format code with Prettier

Multi-Tab Sync

The app uses BroadcastTransport (browser's BroadcastChannel API) for real cross-tab communication:

• First tab becomes the "leader" (holds state, processes events)
• Other tabs are followers (send events to leader, receive state updates)
• No server needed — works entirely in the browser

This demonstrates the transport abstraction: swap BroadcastTransport for a WebSocketTransport to connect to a real server.

Tech Stack

• Package Manager: pnpm 9+
• Language: TypeScript 5
• Framework: Next.js 16
• Styling: Tailwind CSS 4

Future Improvements

• Validation: Add Zod for runtime validation at API boundaries
• Testing: Vitest, Playwright
• CI/CD: GitHub Actions, Changesets
• Backend: WebSocket server, real transport
• DX: Biome, Turborepo

License

MIT