Skip to main content
This guide covers how to run Brainbox development servers and common development workflows.

​
Start All Services

The fastest way to start all development servers: 
npm run dev
This uses Turbo to run all dev servers in parallel:
  • Server (API) - http://localhost:3000
  • Web (React app) - http://localhost:4000
  • Desktop (Electron) - Opens desktop window
Make sure Docker infrastructure services are running before starting dev servers. See Development Setup for details.

​
Run Individual Services

You can run each service independently for focused development: 
cd apps/server && npm run dev

​
Server (Port 3000)

The Fastify backend API with WebSocket support: 
cd apps/server
npm run dev
Features:
  • Hot reload with tsx watch
  • Loads environment from .env file
  • WebSocket server for real-time sync
  • PostgreSQL database migrations
  • BullMQ background jobs

​
Web App (Port 4000)

The React web application: 
cd apps/web
npm run dev
Features:
  • Hot module replacement (HMR)
  • Vite dev server
  • SQLite WASM database
  • TailwindCSS v4
  • PWA support

​
Desktop App

The Electron desktop application: 
cd apps/desktop
npm run dev
Features:
  • Electron with better-sqlite3
  • Hot reload for renderer and main process
  • Native SQLite database
  • Auto-updates
On Windows, use npm run dev:win to properly set environment variables.

​
Watch Mode

Watch and rebuild core packages automatically: 
npm run watch
This watches changes in:
  • @brainbox/core
  • @brainbox/crdt
  • @brainbox/server
Useful when developing shared packages while running the apps.

​
Development Workflows

​
Type Checking

Run TypeScript compiler without emitting files: 
npm run compile
This runs type checking across all packages in the monorepo.

​
Testing

npm run test
Brainbox uses Vitest for testing. Tests run in watch mode by default in development.

​
Linting and Formatting

npm run lint
The project uses:
  • ESLint - TypeScript, React, and import rules
  • Prettier - Code formatting
  • Husky - Git hooks for pre-commit checks
  • lint-staged - Run linters on staged files

​
Building for Production

npm run build
The build process:
  1. Type checks with TypeScript
  2. Bundles with appropriate tooling (tsup, Vite, Electron Forge)
  3. Outputs to dist/ directories

​
Debug Mode

Enable debug logging for the server: 
DEBUG=brainbox:* npm run dev
This enables detailed logging for all Brainbox modules using the debug package.

​
Database Inspection

Access the PostgreSQL database directly: 
docker exec -it brainbox_postgres psql -U colanode_user -d colanode_db
Useful SQL commands: 
-- List all tables
\dt

-- Describe table schema
\d table_name

-- Query nodes
SELECT * FROM nodes LIMIT 10;

-- Check migrations
SELECT * FROM migrations;

​
Common Development Tasks

​
Reset Database

To start with a fresh database: 
docker compose -f hosting/docker/docker-compose.yaml down -v
docker compose -f hosting/docker/docker-compose.yaml up -d
This will delete all data. Use with caution.

​
Clear Local Storage

For the web app, clear browser storage:
  1. Open DevTools (F12)
  2. Application → Storage → Clear site data
  3. Refresh the page
For desktop app, delete the SQLite database file located in the user data directory.

​
Rebuild Dependencies

If you encounter dependency issues: 
npm run clean
rm -rf node_modules package-lock.json
npm install
For Electron native modules: 
cd apps/desktop
npm run postinstall  # Rebuilds Electron native modules

​
Environment Variables

Key environment variables for local development: 
NODE_ENV=production
SERVER_MODE=standalone
POSTGRES_URL=postgres://colanode_user:postgrespass123@localhost:5432/colanode_db
REDIS_URL=redis://:your_valkey_password@localhost:6379/0
STORAGE_S3_ENDPOINT=http://localhost:9000
STORAGE_S3_ACCESS_KEY=minioadmin
STORAGE_S3_SECRET_KEY=your_minio_password
STORAGE_S3_BUCKET=brainbox
ACCOUNT_VERIFICATION_TYPE=automatic

​
Performance Tips

​
Faster Rebuilds

Use watch mode for packages you’re actively developing: 
npm run watch  # Watches core, crdt, server packages

​
Turbo Cache

Turbo caches build outputs. To clear the cache: 
npx turbo clean

​
Selective Builds

Build specific packages only: 
npx turbo run build --filter=@brainbox/core
npx turbo run build --filter=@brainbox/server

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us