Environment Variables and Configuration Reference

Chat App is configured entirely through environment variables loaded by dotenv at server startup. A single .env file at the repository root drives both the backend runtime and the security behaviour of authentication cookies — there is no separate config file for the frontend, because the Vite dev server reads its proxy settings from vite.config.js directly. The sections below document every supported variable, its effect on the running application, and security considerations you should be aware of before deploying.

Environment Variables

MONGO_DB_URI

string

required

The connection string Mongoose uses to connect to your MongoDB deployment. Accepted formats include a local mongod URI and a MongoDB Atlas SRV string.

# Local MongoDB
MONGO_DB_URI=mongodb://localhost:27017/chat-app

# MongoDB Atlas
MONGO_DB_URI=mongodb+srv://<username>:<password>@cluster0.example.mongodb.net/chat-app?retryWrites=true&w=majority

JWT_SECRET

string

required

The secret key used by jsonwebtoken to sign and verify JWT tokens. Tokens are issued with a 15-day expiry (expiresIn: "15d"). In production this value must be a randomly generated, high-entropy string.

JWT_SECRET=replace_with_a_32_plus_character_random_string

Generate a suitable value with:

openssl rand -hex 32

PORT

number

default:"4000"

The TCP port the Express HTTP server (and the Socket.io server attached to the same http.Server instance) listens on. If omitted, the server defaults to 4000.

PORT=4000

NODE_ENV

string

default:"development"

Controls environment-specific behaviour. The only value that changes runtime behaviour is production, which enables the secure flag on the JWT cookie (see Cookie Security below).

# Development (default) — secure cookie flag is OFF
NODE_ENV=development

# Production — secure cookie flag is ON
NODE_ENV=production

.env File Location

The .env file must be placed at the repository root — the same directory that contains the /backend and /frontend folders — not inside either of those subdirectories.

Chat-App/          ← .env goes here
├── backend/
├── frontend/
├── package.json
└── .env

dotenv.config() is called in backend/server.js using a path resolved from the Node.js working directory. Running npm run server from the repo root means the current working directory is the repo root, so .env is found automatically.

JWT tokens are transmitted as HttpOnly cookies set by the /api/auth/login and /api/auth/signup routes. The following cookie attributes are applied on every response regardless of environment:

Attribute	Value	Purpose
`httpOnly`	`true`	Prevents JavaScript from reading the cookie (anti-XSS)
`sameSite`	`strict`	Blocks the cookie from being sent in cross-site requests (anti-CSRF)
`maxAge`	15 days	Matches the JWT `expiresIn` so the cookie and token expire together

The secure attribute is conditional:

secure: process.env.NODE_ENV !== "development"

When NODE_ENV is anything other than "development" (including "production"), the browser will only transmit the cookie over HTTPS connections. Always set NODE_ENV=production when deploying behind TLS.

CORS and Socket.io

Never commit JWT_SECRET to version control. Add .env to your .gitignore file and use a secrets manager (AWS Secrets Manager, Doppler, Railway variables, etc.) to inject it in production.

The Socket.io server is initialised with an explicit CORS allowlist:

const io = new Server(server, {
  cors: {
    origin: ["http://localhost:3000"],
    methods: ["GET", "POST"],
  },
});

This origin is relevant only during local development when the Vite dev server and the Express server run on different ports and a browser same-origin policy would otherwise block the WebSocket upgrade. In the single-origin production deployment (where Express serves the compiled React build directly on PORT), the browser and the server share the same origin, so no cross-origin headers are needed — the CORS configuration in the Socket.io initialiser is effectively bypassed and all WebSocket connections succeed without modification. If you run the frontend dev server on a port other than 3000 during development, update the origin array in backend/socket/socket.js to match (e.g. http://localhost:5173).

Get Started

Core Features

Architecture

Deployment

Environment Variables and Configuration Reference