Installation & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
The installation and local setup process for Dreamcats establishes a full-stack development environment utilizing Bun as the primary package manager and runtime. The architecture is split between a React-based frontend powered by Vite and a real-time backend hosted on Convex.
This guide covers dependency installation, environment configuration, and the initialization of the Convex development backend. Proper setup ensures that the local frontend can communicate with the synchronized state stored in Convex, enabling multiplayer functionality and real-time game logic.
Sources: README.md:1-5, AGENTS.md:3-8
Prerequisites and Installation
The project requires the Bun runtime for managing dependencies and executing scripts. The initial setup involves cloning the repository and installing the necessary Node modules.
Dependency Management
The bun install command is used to install all dependencies listed in the package.json. These include critical libraries for state management (Zustand), animations (GSAP), and backend communication (Convex).
Sources: README.md:27-31, AGENTS.md:4, package.json:20-80
| Command | Description |
|---|---|
bun install | Installs all project dependencies. |
bunx convex dev | Initializes the Convex project and backend watcher. |
bun run dev | Starts the frontend and backend in parallel. |
Sources: AGENTS.md:4-7, package.json:7-10
Backend Initialization (Convex)
Convex provides the real-time database and serverless functions for Dreamcats. Local development requires a running Convex instance to synchronize state and generate TypeScript types.
Initialization Flow
Running bunx convex dev performs several automated steps:
- Project Creation: Creates a new Convex project if one does not exist.
- Type Generation: Generates TypeScript types within the
convex/_generated/directory based on the schema defined inconvex/schema.ts. - Deployment: Deploys local backend functions to the development environment.
- Backend Watcher: Launches a watcher that redeploys functions on save.
Sources: README.md:33-41, AGENTS.md:5, convex/README.md:1-5
The diagram shows the sequential steps taken by the Convex CLI to synchronize the local development environment with the cloud backend.
Sources: AGENTS.md:5, README.md:33-41
Environment Configuration
A .env file must be created in the root directory to allow the Vite client to connect to the specific Convex deployment.
Required Variables
- VITE_CONVEX_URL: The client-side variable used to point the React application to the Convex backend. This URL is provided by the output of the
bunx convex devcommand. - CONVEX_DEPLOYMENT: Used primarily by deployment scripts and CI environments.
Sources: README.md:43-50, AGENTS.md:24-25
Development Workflow
Once dependencies are installed and the backend is initialized, the project can be run locally using the provided development scripts.
Parallel Execution
The project uses the concurrently package to run the frontend and backend development environments simultaneously.
The sequence diagram illustrates how the dev script orchestrates the startup of both the UI and backend services.
Sources: package.json:8, AGENTS.md:6
Available Scripts
- Dev (UI Only):
bun run dev:ui- Runs the Vite development server. - Dev (Convex Only):
bun run dev:convex- Runs the Convex development environment. - Build:
bun run build- Executestsc -bfor type checking followed byvite build. - Lint:
bun run lint- Runs ESLint across the codebase. - Test:
bun run test- Launches Vitest for unit and integration testing.
Sources: package.json:7-16, AGENTS.md:6-12
Summary
The local setup for Dreamcats is designed for high-velocity development by automating type generation and backend deployments via Convex. By using Bun and the integrated dev script, developers can maintain a synchronized environment where schema changes in the backend are immediately reflected in the frontend TypeScript definitions.
Sources: README.md:33-54, AGENTS.md:3-12