FluxStack Live Components - Interactive Documentation

Interactive documentation and playground for FluxStack Live Components — server-side reactive components synchronized in real-time via WebSocket.

What are Live Components?

Live Components are React components whose state lives on the server. When the state changes server-side, it automatically synchronizes with the frontend via WebSocket. The frontend renders the received state and sends actions back to the server.

Inspired by Laravel Livewire and Phoenix LiveView.

Features Covered

• Server-Side State — State managed on the server with automatic sync
• Reactive Proxy — Direct property mutation (this.count++) auto-syncs
• Room Events — Multi-user real-time synchronization
• Form Binding — $field() helper for form state management
• Server Tasks — Background tasks with setInterval (clock example)
• Live Cursors — Real-time mouse cursor sharing across users
• State Signing — HMAC-SHA256 signed state with rehydration on reconnect
• Persistence — Automatic localStorage persistence with signature validation

Live Demos

The documentation includes interactive demos you can try directly:

Demo	Description
Counter	Increment/decrement with server-side state
Shared Counter	Two instances in the same room syncing in real-time
Form	$field() binding with blur/change/debounce strategies
Server Clock	setInterval running on the server, pushing time every second
Live Cursors	See everyone's mouse cursor in real-time (toggle via navbar)

Getting Started

# Install dependencies
bun install

# Start development (backend + frontend)
bun run dev

• Frontend: http://localhost:5173
• Backend: http://localhost:3000
• Swagger: http://localhost:3000/swagger

Project Structure

LiveComponentsDocs/
├── app/
│   ├── server/
│   │   └── live/              # Server-side Live Components
│   │       ├── LiveCounter.ts
│   │       ├── LiveLocalCounter.ts
│   │       ├── LiveForm.ts
│   │       ├── LiveClock.ts
│   │       └── LiveCursors.ts
│   ├── client/
│   │   └── src/
│   │       ├── pages/
│   │       │   └── LiveDocsPage.tsx   # Main documentation page
│   │       ├── live/                   # Client-side demo components
│   │       │   ├── CounterDemo.tsx
│   │       │   ├── ClockDemo.tsx
│   │       │   └── CursorsDemo.tsx
│   │       └── components/
│   │           └── AppLayout.tsx       # Layout with cursor overlay
│   └── shared/
├── core/                      # FluxStack framework (read-only)
├── config/                    # App configuration
└── LLMD/                      # LLM-optimized documentation

Tech Stack

• Runtime: Bun >= 1.2.0
• Backend: Elysia.js 1.4.6
• Frontend: React 19 + Vite 7
• Styling: Tailwind CSS 4
• Diagrams: Mermaid.js (architecture & flow diagrams)
• Type Safety: TypeScript 5.8 + Eden Treaty

Quick Example

Server (app/server/live/LiveCounter.ts):

import { LiveComponent } from '@core/types/types'

export class LiveCounter extends LiveComponent<typeof LiveCounter.defaultState> {
  static componentName = 'LiveCounter'
  static defaultState = { count: 0 }

  declare count: number

  async increment() {
    this.count++ // Auto-sync via Proxy!
    return { success: true }
  }
}

Client (app/client/src/live/CounterDemo.tsx):

import { Live } from '@/core/client'
import { LiveCounter } from '@server/live/LiveCounter'

export function CounterDemo() {
  const counter = Live.use(LiveCounter)

  return (
    <div>
      <p>{counter.$state.count}</p>
      <button onClick={() => counter.increment()}>+</button>
    </div>
  )
}

Links

• FluxStack Framework

---

Built with FluxStack