Skip to content

DEVELOPER.md

Latest commit

 

History

History
203 lines (142 loc) · 5.69 KB

DEVELOPER.md

File metadata and controls

203 lines (142 loc) · 5.69 KB

Development

These are a few commands to get you started building the client locally.

Quick Start

# Install dependencies
npm install

# Build the client
npm run build

# Start dev server
npm run dev

Open http://localhost:5173 and connect with your XMPP credentials.

After a git pull: if dependencies have changed, re-run npm install before building. Missing packages are the most common cause of Cannot find module errors after syncing.

Available Scripts

Command Description
npm run dev Start the web client dev server
npm run build Build SDK and app for production
npm run build:sdk Build the React SDK only
npm run build:app Build the web client only
npm run test Run all tests
npm run typecheck Type-check all packages
npm run lint Run ESLint on all packages
npm run tauri:dev Run desktop app in development mode
npm run tauri:build Build desktop app for distribution
npm run screenshots Generate demo screenshots (see below)

Screenshots

Generate marketing and documentation screenshots from the demo mode using Playwright:

# One-time setup: install Chromium for Playwright
npx playwright install chromium

# Generate all screenshots (starts dev server automatically if needed)
npm run screenshots

This produces 10 PNG files in the screenshots/ directory covering major features in both dark and light mode: 1:1 chat, group chat with members panel, conversation list, contacts, polls, code blocks, admin dashboard, and settings.

The script navigates the demo at /demo.html?tutorial=false, freezes the animation timeline, and captures each view at 1280×800. To add or modify screenshots, edit scripts/screenshots.ts.

Troubleshooting

Clear Local Storage

If the desktop app enters a connection loop or has stale configuration from a previous version, you can reset all local data (localStorage, sessionStorage, IndexedDB) by launching with the --clear-storage flag:

fluux --clear-storage

Short form:

fluux -c

This clears persisted store data (e.g., stale wss:// server URLs) without requiring manual intervention in browser dev tools. The flag is processed on the Rust side and emits an event to the frontend, which calls clearLocalData() before the app initializes.

Debugging

The desktop app supports verbose logging to diagnose connection issues, freezes, and render loops:

# Enable verbose logging (Rust tracing + WebView console forwarded to stderr)
fluux --verbose 2>&1 | tee fluux-debug.log

# Fine-grained control with RUST_LOG
RUST_LOG=debug fluux 2>&1 | tee fluux-debug.log

# Show available CLI flags
fluux --help

When --verbose is active:

  • Rust-side tracing from the XMPP proxy (SRV resolution, WebSocket, STARTTLS) prints to stderr
  • WebView console.log/warn/error messages are forwarded to stderr
  • Startup diagnostics show version, platform, and GPU workaround status (Linux)

For deep SDK connection/proxy tracing (high-volume logs such as machine transitions, disconnect phase timing, and proxy op lifecycle), enable the connection trace flag:

# Desktop / Node environment
FLUUX_DEBUG_CONNECTION_TRACE=1 fluux --verbose

In a browser/WebView dev console:

localStorage.setItem('DEBUG_CONNECTION_TRACE', 'true')
// optional global toggle
globalThis.__FLUUX_DEBUG_CONNECTION_TRACE__ = true

Build-time (Vite) toggle:

VITE_FLUUX_DEBUG_CONNECTION_TRACE=true npm run tauri:dev

Disable again with:

localStorage.removeItem('DEBUG_CONNECTION_TRACE')
delete globalThis.__FLUUX_DEBUG_CONNECTION_TRACE__

On Linux, GPU rendering is enabled by default. If rendering issues occur, set FLUUX_DISABLE_GPU=1 to apply WebKitGTK GPU workarounds.

The environment variable NO_COLOR can be set to disable console color output. It can be useful to redirect the output to a file:

NO_COLOR=1 ./fluux --verbose=xmpp 2> xmpp-debug.log

Building Debian Packages

You can build .deb packages locally using standard Debian tooling.

Prerequisites

Install Node.js 22 (Ubuntu 22.04 LTS version is too old):

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

Install Rust via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Install system dependencies:

sudo apt-get install -y \
  debhelper \
  devscripts \
  nodejs \
  libwebkit2gtk-4.1-dev \
  libgtk-3-dev \
  libayatana-appindicator3-dev \
  libxss-dev \
  librsvg2-dev \
  libssl-dev \
  pkg-config \
  patchelf

Build from Source

To build the .deb package from scratch (compiles everything):

# From repository root (-d skips dpkg's dependency check for rustup-installed Rust)
dpkg-buildpackage -d -uc -us -b

This will:

  1. Install npm dependencies
  2. Build the SDK
  3. Build the Tauri binary
  4. Package everything into a .deb file

The resulting package will be created in the parent directory: ../fluux-messenger_<version>_<arch>.deb

Build with Pre-built Binary

If you've already built the binary with Tauri, you can skip the build step:

# First build with Tauri
npm run tauri:build

# Then package (auto-detects existing binary)
dpkg-buildpackage -d -uc -us -b

Or explicitly specify the binary path:

FLUUX_BINARY=apps/fluux/src-tauri/target/release/fluux dpkg-buildpackage -d -uc -us -b

Install the Package

sudo dpkg -i ../fluux-messenger_*.deb
sudo apt-get install -f  # Fix any missing dependencies