Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/abdelhafid37/talkbox/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through every step needed to run TalkBox on your local machine — from cloning the repository to opening a conversation between two browser tabs. The server starts on port 3000 and the Vite dev server on port 5173; both are pre-configured in the provided .env.example files so you need only supply a MongoDB connection string and a JWT secret to be up and running.

​
Prerequisites

Make sure you have the following before you start:
  • Node.js 18 or later — nodejs.org
  • npm (bundled with Node.js)
  • MongoDB instance — a locally running MongoDB daemon, or a free MongoDB Atlas cluster URI

​
Setup Steps

1

Clone the repository

Clone TalkBox from GitHub and move into the project root.
git clone https://github.com/abdelhafid37/talkbox.git
cd talkbox
The repository contains two independent packages — server/ and client/ — each with their own package.json and .env.example. You will configure and start them separately.
2

Configure the server environment

Copy the example environment file and fill in the required values.
cd server
cp .env.example .env
Open .env in your editor and set each variable:
PORT=3000
MONGO_URI=mongodb+srv://<user>:<password>@cluster0.example.mongodb.net/talkbox
JWT_SECRET=your-super-secret-key-change-this
CLIENT_URL=http://localhost:5173
VariableDescription
PORTThe port the Express server listens on. Defaults to 3000.
MONGO_URIFull MongoDB connection string. Can be a local URI such as mongodb://localhost:27017/talkbox or an Atlas connection string.
JWT_SECRETA long, random string used to sign and verify JSON Web Tokens. Use at least 32 characters in production.
CLIENT_URLThe origin of the React app. Used by Express CORS and Socket.IO CORS to allow cross-origin requests. Keep http://localhost:5173 for local development.
Never commit your .env file. The repository’s .gitignore excludes it, but double-check before pushing to a public remote.
3

Start the server

Install dependencies and start the server with nodemon for live reloading.
npm install
npm run dev
The startup sequence connects to MongoDB first, then begins listening on the configured port, and finally attaches the Socket.IO server:
[DATABASE] Connected to MongoDB.
[SERVER] Running on port 3000
If you see [DATABASE] Failed to connect to MongoDB, verify your MONGO_URI is correct and that your Atlas cluster IP allowlist includes your current IP address.
4

Configure the client environment

Open a new terminal, navigate to the client/ directory, and copy its environment file.
cd ../client
cp .env.example .env
The default values in .env.example already point to the local server, so no changes are needed for local development:
VITE_API_URL=http://localhost:3000
VariableDescription
VITE_API_URLBase URL for all Axios REST requests and the Socket.IO connection. Must match the server’s address and port.
Vite only exposes environment variables prefixed with VITE_ to client-side code. Any variable without this prefix is ignored at build time.
5

Start the client

Install dependencies and launch the Vite development server.
npm install
npm run dev
Vite will print the local URL once the build is ready:
VITE v8.x.x  ready in Xms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
Open http://localhost:5173 in your browser. You will be redirected to the login page because no session exists yet.
6

Register two accounts and start chatting

To test real-time messaging you need two separate sessions.
  1. In your first browser tab, navigate to Register, create an account (e.g. alice), and log in.
  2. Open a second browser tab (or a private/incognito window), navigate to Register, create a second account (e.g. bob), and log in.
  3. In Alice’s tab, find Bob in the user list on the left sidebar and click his name to open a conversation.
  4. Type a message and press Send. Bob’s tab will receive the message instantly via the newMessage Socket.IO event — no refresh needed.
  5. Switch to Bob’s tab and reply. You will see both sides of the conversation update in real time.
Both accounts will also appear in each other’s online users list as long as both tabs remain open.
MongoDB Atlas offers a free M0 shared cluster with 512 MB of storage — more than enough for local development and small deployments. Create a free account, spin up a cluster, and copy the connection string into your MONGO_URI. Make sure to:
  • Add your IP address to the Network Access allowlist (or use 0.0.0.0/0 during development).
  • Replace <password> in the connection string with your database user’s actual password.
  • Append a database name at the end of the URI, e.g. .../talkbox?retryWrites=true&w=majority.

​
Verifying a Healthy Startup

When both processes are running correctly, your two terminals should look like this: Server terminal 
[DATABASE] Connected to MongoDB.
[SERVER] Running on port 3000
After the first user logs in and their client emits the join event, you will also see: 
[SOCKET.IO] [CONNECTION] Client connected: <socketId>.
[SOCKET.IO] [JOIN] alice joined with socket <socketId>.
Map(1) { '<userId>' => '<socketId>' }
Client terminal 
VITE v8.x.x  ready in Xms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
If the client cannot reach the server (for example, a wrong VITE_API_URL), Axios requests will fail with a network error and the Socket.IO connection will not establish. Confirm both values point to http://localhost:3000 and that the server process is still running.

Build docs developers (and LLMs) love

Get started for freeTalk to us