Real-time Chat Application

Learn how to build a full-featured real-time chat application using kSync with WebSocket synchronization, React hooks, and event-sourcing.

Overview

This example demonstrates:

Real-time messaging with WebSocket sync
User presence and typing indicators
Message history with pagination
Optimistic updates for instant UX
Offline support with automatic reconnection

Server Setup

First, let’s create a simple WebSocket server:

server.ts

import { WebSocketServer } from 'ws';
import { createServer } from 'http';

const server = createServer();
const wss = new WebSocketServer({ server });

interface Client {
  id: string;
  ws: any;
  room: string;
  user: { id: string; name: string; avatar?: string };
}

const clients = new Map<string, Client>();

wss.on('connection', (ws, request) => {
  const clientId = generateId();
  
  ws.on('message', (data) => {
    try {
      const message = JSON.parse(data.toString());
      
      switch (message.type) {
        case 'join':
          handleJoin(clientId, ws, message);
          break;
        case 'event':
          handleEvent(clientId, message);
          break;
        case 'presence':
          handlePresence(clientId, message);
          break;
      }
    } catch (error) {
      console.error('Message handling error:', error);
    }
  });

  ws.on('close', () => {
    handleDisconnect(clientId);
  });
});

function handleJoin(clientId: string, ws: any, message: any) {
  const client: Client = {
    id: clientId,
    ws,
    room: message.room,
    user: message.user
  };
  
  clients.set(clientId, client);
  
  // Send join confirmation
  ws.send(JSON.stringify({
    type: 'joined',
    clientId,
    room: message.room
  }));
  
  // Notify other clients in the room
  broadcastToRoom(message.room, {
    type: 'user_joined',
    user: message.user
  }, clientId);
}

function handleEvent(clientId: string, message: any) {
  const client = clients.get(clientId);
  if (!client) return;
  
  // Broadcast event to all clients in the same room
  broadcastToRoom(client.room, {
    type: 'event',
    event: message.event
  });
}

function handlePresence(clientId: string, message: any) {
  const client = clients.get(clientId);
  if (!client) return;
  
  // Broadcast presence update to room
  broadcastToRoom(client.room, {
    type: 'presence',
    userId: client.user.id,
    presence: message.presence
  }, clientId);
}

function broadcastToRoom(room: string, message: any, excludeClient?: string) {
  for (const [id, client] of clients) {
    if (client.room === room && id !== excludeClient) {
      client.ws.send(JSON.stringify(message));
    }
  }
}

function handleDisconnect(clientId: string) {
  const client = clients.get(clientId);
  if (client) {
    broadcastToRoom(client.room, {
      type: 'user_left',
      userId: client.user.id
    }, clientId);
    clients.delete(clientId);
  }
}

function generateId() {
  return Math.random().toString(36).substring(2, 15);
}

server.listen(8080, () => {
  console.log('Chat server running on port 8080');
});

Chat Store Setup

Create the chat store with kSync:

stores/chatStore.ts

import { 
  KSync, 
  InMemoryStorage, 
  WebSocketSyncClient 
} from 'ksync';

export interface Message {
  id: string;
  text: string;
  author: User;
  timestamp: number;
  edited?: boolean;
  replyTo?: string;
}

export interface User {
  id: string;
  name: string;
  avatar?: string;
  status: 'online' | 'away' | 'offline';
}

export interface ChatState {
  messages: Message[];
  users: Map<string, User>;
  typingUsers: Set<string>;
  currentUser: User | null;
}

// Create chat store
export const createChatStore = (roomId: string, user: User) => {
  const ksync = new KSync<ChatState>({
    storage: new InMemoryStorage(),
    syncClient: new WebSocketSyncClient('ws://localhost:8080', {
      auth: { type: 'none' }
    })
  });

  // Set up materializer to compute chat state from events
  ksync.materialize((events) => {
    const state: ChatState = {
      messages: [],
      users: new Map(),
      typingUsers: new Set(),
      currentUser: user
    };

    for (const event of events) {
      switch (event.type) {
        case 'user_joined':
          state.users.set(event.data.id, event.data);
          break;

        case 'user_left':
          state.users.delete(event.data.userId);
          state.typingUsers.delete(event.data.userId);
          break;

        case 'message_sent':
          state.messages.push(event.data);
          state.typingUsers.delete(event.data.author.id);
          break;

        case 'message_edited':
          const messageIndex = state.messages.findIndex(
            m => m.id === event.data.messageId
          );
          if (messageIndex >= 0) {
            state.messages[messageIndex] = {
              ...state.messages[messageIndex],
              text: event.data.text,
              edited: true
            };
          }
          break;

        case 'message_deleted':
          state.messages = state.messages.filter(
            m => m.id !== event.data.messageId
          );
          break;

        case 'user_typing':
          if (event.data.isTyping) {
            state.typingUsers.add(event.data.userId);
          } else {
            state.typingUsers.delete(event.data.userId);
          }
          break;

        case 'user_status_changed':
          const user = state.users.get(event.data.userId);
          if (user) {
            user.status = event.data.status;
          }
          break;
      }
    }

    // Sort messages by timestamp
    state.messages.sort((a, b) => a.timestamp - b.timestamp);

    return state;
  });

  // Connect to the room
  ksync.connect().then(() => {
    // Send join event
    ksync.syncClient?.send({
      type: 'join',
      room: roomId,
      user
    });

    // Emit user joined event
    ksync.emit('user_joined', user);
  });

  return ksync;
};

React Chat Component

Create the main chat component using kSync React hooks:

components/ChatRoom.tsx

import React, { useState, useEffect, useRef } from 'react';
import { 
  useKSync, 
  useKSyncEvent, 
  useKSyncOptimistic,
  useKSyncPresence 
} from 'ksync/react';
import { createChatStore, Message, User } from '../stores/chatStore';

interface ChatRoomProps {
  roomId: string;
  currentUser: User;
}

export const ChatRoom: React.FC<ChatRoomProps> = ({ roomId, currentUser }) => {
  const [chatStore] = useState(() => createChatStore(roomId, currentUser));
  const { ksync, isConnected } = useKSync(chatStore);
  const messagesEndRef = useRef<HTMLDivElement>(null);
  
  // Get current state with optimistic updates
  const { state: chatState, optimisticUpdate } = useKSyncOptimistic(
    ksync,
    (state) => state
  );

  // Handle real-time events
  useKSyncEvent(ksync, 'message_sent', (event) => {
    // Scroll to bottom when new message arrives
    setTimeout(() => scrollToBottom(), 100);
  });

  // Presence management
  const { presence, updatePresence } = useKSyncPresence(ksync, {
    status: 'online',
    lastSeen: Date.now()
  });

  const scrollToBottom = () => {
    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
  };

  useEffect(() => {
    scrollToBottom();
  }, [chatState.messages.length]);

  return (
    <div className="chat-room">
      <ChatHeader 
        roomId={roomId}
        users={chatState.users}
        isConnected={isConnected}
      />
      
      <MessageList 
        messages={chatState.messages}
        currentUser={currentUser}
        typingUsers={chatState.typingUsers}
      />
      
      <div ref={messagesEndRef} />
      
      <MessageInput 
        ksync={ksync}
        currentUser={currentUser}
        optimisticUpdate={optimisticUpdate}
      />
    </div>
  );
};

Message Components

components/MessageList.tsx

import React from 'react';
import { Message, User } from '../stores/chatStore';

interface MessageListProps {
  messages: Message[];
  currentUser: User;
  typingUsers: Set<string>;
}

export const MessageList: React.FC<MessageListProps> = ({
  messages,
  currentUser,
  typingUsers
}) => {
  return (
    <div className="message-list">
      {messages.map((message) => (
        <MessageItem
          key={message.id}
          message={message}
          isOwn={message.author.id === currentUser.id}
        />
      ))}
      
      {typingUsers.size > 0 && (
        <TypingIndicator userIds={Array.from(typingUsers)} />
      )}
    </div>
  );
};

interface MessageItemProps {
  message: Message;
  isOwn: boolean;
}

const MessageItem: React.FC<MessageItemProps> = ({ message, isOwn }) => {
  return (
    <div className={`message ${isOwn ? 'own' : 'other'}`}>
      <div className="message-header">
        <img 
          src={message.author.avatar || '/default-avatar.png'} 
          alt={message.author.name}
          className="avatar"
        />
        <span className="author">{message.author.name}</span>
        <span className="timestamp">
          {new Date(message.timestamp).toLocaleTimeString()}
        </span>
        {message.edited && <span className="edited">edited</span>}
      </div>
      <div className="message-content">
        {message.text}
      </div>
    </div>
  );
};

const TypingIndicator: React.FC<{ userIds: string[] }> = ({ userIds }) => {
  return (
    <div className="typing-indicator">
      <span className="typing-dots">...</span>
      <span>{userIds.length === 1 ? 'Someone is' : 'People are'} typing</span>
    </div>
  );
};

Message Input Component

components/MessageInput.tsx

import React, { useState, useRef, useEffect } from 'react';
import { KSync } from 'ksync';
import { User, Message } from '../stores/chatStore';

interface MessageInputProps {
  ksync: KSync;
  currentUser: User;
  optimisticUpdate: (updater: (state: any) => any) => void;
}

export const MessageInput: React.FC<MessageInputProps> = ({
  ksync,
  currentUser,
  optimisticUpdate
}) => {
  const [text, setText] = useState('');
  const [isTyping, setIsTyping] = useState(false);
  const typingTimeoutRef = useRef<NodeJS.Timeout>();
  const inputRef = useRef<HTMLTextAreaElement>(null);

  const handleInputChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
    setText(e.target.value);
    
    // Handle typing indicators
    if (!isTyping && e.target.value.length > 0) {
      setIsTyping(true);
      ksync.emit('user_typing', {
        userId: currentUser.id,
        isTyping: true
      });
    }

    // Clear existing timeout
    if (typingTimeoutRef.current) {
      clearTimeout(typingTimeoutRef.current);
    }

    // Set timeout to stop typing indicator
    typingTimeoutRef.current = setTimeout(() => {
      setIsTyping(false);
      ksync.emit('user_typing', {
        userId: currentUser.id,
        isTyping: false
      });
    }, 2000);
  };

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    
    if (!text.trim()) return;

    const messageId = generateId();
    const message: Message = {
      id: messageId,
      text: text.trim(),
      author: currentUser,
      timestamp: Date.now()
    };

    // Optimistic update - add message immediately
    optimisticUpdate((state) => ({
      ...state,
      messages: [...state.messages, message]
    }));

    // Clear input and typing state
    setText('');
    setIsTyping(false);
    
    // Stop typing indicator
    ksync.emit('user_typing', {
      userId: currentUser.id,
      isTyping: false
    });

    try {
      // Send actual message event
      await ksync.emit('message_sent', message);
    } catch (error) {
      console.error('Failed to send message:', error);
      // In a real app, you might want to show an error indicator
      // and allow retry
    }

    // Focus back to input
    inputRef.current?.focus();
  };

  const handleKeyDown = (e: React.KeyboardEvent) => {
    if (e.key === 'Enter' && !e.shiftKey) {
      e.preventDefault();
      handleSubmit(e);
    }
  };

  return (
    <form onSubmit={handleSubmit} className="message-input">
      <textarea
        ref={inputRef}
        value={text}
        onChange={handleInputChange}
        onKeyDown={handleKeyDown}
        placeholder="Type a message..."
        rows={1}
        className="input-field"
      />
      <button 
        type="submit" 
        disabled={!text.trim()}
        className="send-button"
      >
        Send
      </button>
    </form>
  );
};

function generateId() {
  return Math.random().toString(36).substring(2, 15);
}

Chat Header Component

components/ChatHeader.tsx

import React from 'react';
import { User } from '../stores/chatStore';

interface ChatHeaderProps {
  roomId: string;
  users: Map<string, User>;
  isConnected: boolean;
}

export const ChatHeader: React.FC<ChatHeaderProps> = ({
  roomId,
  users,
  isConnected
}) => {
  const onlineUsers = Array.from(users.values()).filter(
    user => user.status === 'online'
  );

  return (
    <div className="chat-header">
      <div className="room-info">
        <h2>Room: {roomId}</h2>
        <div className="connection-status">
          <span className={`status-dot ${isConnected ? 'connected' : 'disconnected'}`} />
          {isConnected ? 'Connected' : 'Disconnected'}
        </div>
      </div>
      
      <div className="user-list">
        <span className="user-count">
          {onlineUsers.length} online
        </span>
        
        <div className="user-avatars">
          {onlineUsers.slice(0, 5).map(user => (
            <img
              key={user.id}
              src={user.avatar || '/default-avatar.png'}
              alt={user.name}
              title={user.name}
              className="user-avatar"
            />
          ))}
          {onlineUsers.length > 5 && (
            <span className="more-users">
              +{onlineUsers.length - 5}
            </span>
          )}
        </div>
      </div>
    </div>
  );
};

App Component

App.tsx

import React, { useState } from 'react';
import { KSyncProvider } from 'ksync/react';
import { ChatRoom } from './components/ChatRoom';
import { User } from './stores/chatStore';
import './styles/chat.css';

function App() {
  const [currentUser] = useState<User>({
    id: generateUserId(),
    name: `User_${Math.random().toString(36).substring(2, 8)}`,
    avatar: `https://avatars.dicebear.com/api/avataaars/${Math.random()}.svg`,
    status: 'online'
  });

  const [roomId] = useState('general');

  return (
    <KSyncProvider>
      <div className="app">
        <header className="app-header">
          <h1>kSync Chat</h1>
          <div className="user-info">
            <img src={currentUser.avatar} alt={currentUser.name} />
            <span>{currentUser.name}</span>
          </div>
        </header>
        
        <main className="app-main">
          <ChatRoom roomId={roomId} currentUser={currentUser} />
        </main>
      </div>
    </KSyncProvider>
  );
}

function generateUserId() {
  return `user_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
}

export default App;

Styling

styles/chat.css

.app {
  height: 100vh;
  display: flex;
  flex-direction: column;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}

.app-header {
  background: #2c3e50;
  color: white;
  padding: 1rem;
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.user-info {
  display: flex;
  align-items: center;
  gap: 0.5rem;
}

.user-info img {
  width: 32px;
  height: 32px;
  border-radius: 50%;
}

.chat-room {
  flex: 1;
  display: flex;
  flex-direction: column;
  height: 100%;
}

.chat-header {
  background: #ecf0f1;
  padding: 1rem;
  border-bottom: 1px solid #bdc3c7;
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.connection-status {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  font-size: 0.875rem;
}

.status-dot {
  width: 8px;
  height: 8px;
  border-radius: 50%;
}

.status-dot.connected {
  background: #27ae60;
}

.status-dot.disconnected {
  background: #e74c3c;
}

.user-list {
  display: flex;
  align-items: center;
  gap: 1rem;
}

.user-avatars {
  display: flex;
  align-items: center;
  gap: 0.25rem;
}

.user-avatar {
  width: 24px;
  height: 24px;
  border-radius: 50%;
  border: 2px solid white;
}

.message-list {
  flex: 1;
  padding: 1rem;
  overflow-y: auto;
  background: #f8f9fa;
}

.message {
  margin-bottom: 1rem;
  max-width: 70%;
}

.message.own {
  margin-left: auto;
  text-align: right;
}

.message-header {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  margin-bottom: 0.25rem;
  font-size: 0.875rem;
  color: #6c757d;
}

.message.own .message-header {
  justify-content: flex-end;
}

.message .avatar {
  width: 20px;
  height: 20px;
  border-radius: 50%;
}

.message-content {
  background: white;
  padding: 0.75rem;
  border-radius: 1rem;
  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
}

.message.own .message-content {
  background: #007bff;
  color: white;
}

.typing-indicator {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  font-style: italic;
  color: #6c757d;
  margin: 0.5rem 0;
}

.typing-dots::before {
  content: '';
  display: inline-block;
  width: 8px;
  height: 8px;
  border-radius: 50%;
  background: #6c757d;
  animation: typing 1.5s infinite;
}

@keyframes typing {
  0%, 60%, 100% { opacity: 0; }
  30% { opacity: 1; }
}

.message-input {
  background: white;
  padding: 1rem;
  border-top: 1px solid #dee2e6;
  display: flex;
  gap: 0.5rem;
}

.input-field {
  flex: 1;
  border: 1px solid #ced4da;
  border-radius: 1.5rem;
  padding: 0.75rem 1rem;
  resize: none;
  outline: none;
  font-family: inherit;
}

.input-field:focus {
  border-color: #007bff;
  box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
}

.send-button {
  background: #007bff;
  color: white;
  border: none;
  border-radius: 1.5rem;
  padding: 0.75rem 1.5rem;
  cursor: pointer;
  font-weight: 500;
}

.send-button:disabled {
  background: #6c757d;
  cursor: not-allowed;
}

.send-button:hover:not(:disabled) {
  background: #0056b3;
}

Features Demonstrated

This chat application showcases many kSync features:

Real-time Sync: Messages appear instantly across all connected clients
Event Sourcing: All chat events are stored and can be replayed
Optimistic Updates: Messages appear immediately before server confirmation
Presence: Shows who’s online and typing
Automatic Reconnection: Handles network disruptions gracefully
React Integration: Uses kSync React hooks for clean component integration

Running the Example

Install dependencies:

npm install ksync ws

Start the server:

npx ts-node server.ts

Start the React app:

npm run dev

Open multiple browser tabs to see real-time synchronization in action!

Next Steps

Extend this example with:

Message persistence with SQLite storage
File uploads and media messages
Message reactions and threading
Push notifications
End-to-end encryption
Mobile app with React Native

v0.2 Examples

Legacy Examples

Real-time Chat App

Real-time Chat Application

Overview

Server Setup

Chat Store Setup

React Chat Component

Message Components

Message Input Component

Chat Header Component

App Component

Styling

Features Demonstrated

Running the Example

Next Steps

​Real-time Chat Application

​Overview

​Server Setup

​Chat Store Setup

​React Chat Component

​Message Components

​Message Input Component

​Chat Header Component

​App Component

​Styling

​Features Demonstrated

​Running the Example

​Next Steps

Real-time Chat Application

Overview

Server Setup

Chat Store Setup

React Chat Component

Message Components

Message Input Component

Chat Header Component

App Component

Styling

Features Demonstrated

Running the Example

Next Steps