BetterChat

A modern web client for Rocket.Chat. Connects to any unmodified Rocket.Chat 7.6+ server.

Quick Start

Requires Bun >= 1.3.

bunx @clouder0/betterchat --upstream http://your-rocketchat:3000 --secret your-session-secret

Then open http://localhost:3200 in your browser.

CLI Reference

betterchat --upstream <url> --secret <value> [options]

| Flag | Description | Default | |------|-------------|---------| | --upstream <url> | Rocket.Chat server URL | required | | --secret <value> | Session encryption secret | required | | --port <number> | Listen port | 3200 | | --host <address> | Listen host | 0.0.0.0 | | --no-ui | API-only mode (don't serve frontend) | off |

All flags can also be set via environment variables — see .env.example.

Self-Hosting

Behind a reverse proxy (nginx, Caddy, etc.), set:

bunx @clouder0/betterchat --upstream http://rocketchat:3000 --secret $(openssl rand -hex 32)

Set BETTERCHAT_SESSION_COOKIE_SECURE=true if serving over HTTPS.

Development

# Install dependencies
bun install

# Run backend (API on port 3200)
bun --filter @betterchat/backend dev

# Run frontend (Vite dev server on port 3300)
bun run dev:web

# Typecheck all packages
bun run typecheck

# Run unit tests
bun --filter @betterchat/web test
bun --filter @betterchat/backend test

# Build distributable package
bun run build:dist

Integration Tests

Integration tests require a running Rocket.Chat instance with MongoDB. The test stack uses Docker/Podman Compose:

# Start the test stack (MongoDB + Rocket.Chat + BetterChat backend)
bash scripts/backend-stack-start.sh

# Run integration tests
bash scripts/backend-integration-test.sh

# Tear down
bash scripts/backend-stack-stop.sh

Place your Rocket.Chat test license in tests/integration/fixtures/rocketchat-test-license.txt.

License

MIT