FeaturesRealtimeOverview

Realtime

Aerostack Realtime is a WebSocket-based system for building live, collaborative features. One WebSocket connection per client handles everything: database change events, custom pub/sub, presence tracking, and AI token streaming.

What you can build

  • Live dashboards — react to database INSERT/UPDATE/DELETE automatically
  • Chat — room-based messaging with history and persistence
  • Presence — who’s online, where they are, what they’re doing
  • Collaborative tools — sync state between users without a backend
  • AI streaming — stream LLM tokens to 1000 users over a single channel

How it works

Every client connects via a single WebSocket to wss://api.aerostack.ai/api/realtime. From there, they subscribe to topics. Messages flow through those topics.

There are two kinds of topics:

Topic formatExampleHow events arrive
tableName (no slash)ordersAutomatic — ChangeTracker polls D1 every 200ms
path/name (with slash)chat/generalManual — your server calls sdk.socket.emit()

Quick start

import { useAerostack } from '@aerostack/react'
import { useEffect, useState } from 'react'
 
function LiveFeed() {
  const { realtime } = useAerostack()
  const [events, setEvents] = useState([])
 
  useEffect(() => {
    const channel = realtime.channel('orders')
 
    channel
      .on('INSERT', ({ data }) => setEvents(prev => [data, ...prev]))
      .on('UPDATE', ({ data }) => setEvents(prev =>
        prev.map(e => e.id === data.id ? data : e)
      ))
      .subscribe()
 
    return () => channel.unsubscribe()
  }, [realtime])
 
  return (
    <ul>
      {events.map(e => <li key={e.id}>{e.status}</li>)}
    </ul>
  )
}

Connection management

The RealtimeClient handles reconnection automatically with exponential backoff. You can observe the connection status:

realtime.onStatusChange((status) => {
  // 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'disconnected'
  console.log('Connection status:', status)
})

Next steps

ConfigurationDatabase Subscriptions