AlphaBattle is a competitive, real-time implementation of the popular word-guessing game. Unlike the classic single-player version, this project allows users to create private rooms and race against friends to guess the secret word first.
Built with TypeScript, TanStack Start, and Socket.io for seamless bi-directional communication.
- Real-Time Gameplay: See progress (guess count and colors) instantly without spoiling the word.
- Room System: Create private lobbies with unique codes.
- Full Type Safety: Shared strict typing between Frontend and Backend events.
- Live Feedback: Instant "Green/Yellow/Gray" validation logic processed on the server.
- Victory Conditions: First to guess wins; global announcements and confetti effects.
- Persistence: Game results and history stored via Prisma & PostgreSQL.
- Framework: TanStack Start (React)
- Language: TypeScript
- Real-time Engine: Socket.io
- Database: PostgreSQL
- ORM: Prisma
- Styling: Tailwind CSS & Shadcn/UI
- Deployment: Node.js (Custom Server)
- Node.js (v18+)
- PostgreSQL (or Docker to run a container)
-
Clone the repository
git clone [https://github.com/yourusername/alphabattle.git](https://github.com/yourusername/alphabattle.git) cd alphabattle -
Install dependencies
npm install
-
Environment Setup
Create a
.envfile in the root directory:DATABASE_URL="postgresql://user:password@localhost:5432/alphabattle" VITE_SOCKET_URL=http://localhost:3001 -
Database Migration
npx prisma generate npx prisma db push
-
Run the Project
You need to run both the frontend application and the Socket server.
# Terminal 1: Start the Socket Server npm run socket # Terminal 2: Start the Frontend npm run dev
- Shared Types: The project uses a monorepo-like structure for types, ensuring that socket.emit on the client strictly matches socket.on on the server.
- Server-Side Validation: All game logic (word checking, win conditions) happens on the server to prevent cheating.
- Optimistic UI: The frontend reacts immediately to inputs while awaiting server confirmation.