> ## Documentation Index
> Fetch the complete documentation index at: https://ksync.klastra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get up and running with kSync v0.2 in under 2 minutes

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @klastra/ksync
  ```

  ```bash yarn theme={null}
  yarn add @klastra/ksync
  ```

  ```bash pnpm theme={null}
  pnpm add @klastra/ksync
  ```

  ```bash bun theme={null}
  bun add @klastra/ksync
  ```
</CodeGroup>

<Note>
  **No dependencies required!** kSync v0.2 works out of the box with smart defaults. Zod is now optional for advanced schema validation.
</Note>

## Quick Start (30 seconds)

The fastest way to get real-time sync working:

```typescript theme={null}
import { createKSync } from '@klastra/ksync';

// Works instantly with smart defaults
const ksync = createKSync();

// Listen for events
ksync.on('message', (data, event) => {
  console.log(`${event.userId}: ${data.text}`);
});

// Send events (instant local, auto-synced if server configured)
await ksync.send('message', {
  text: 'Hello world!',
  timestamp: Date.now()
});

// Get current state
const state = ksync.getState();
```

## Factory Functions (Optimized Presets)

kSync v0.2 provides factory functions optimized for different use cases:

<Tabs>
  <Tab title="Chat Application">
    ```typescript theme={null}
    import { createChat } from '@klastra/ksync';

    // Chat with presence and optimized batching
    const chat = createChat('my-room', {
      serverUrl: 'ws://localhost:8080'
    });

    // Set user presence
    await chat.setPresence({
      status: 'online',
      metadata: { name: 'Alice', avatar: 'avatar-url' }
    });

    // Send messages
    await chat.send('message', {
      text: 'Hello everyone!',
      author: 'Alice',
      timestamp: Date.now()
    });

    // Listen for messages and presence
    chat.on('message', (data) => {
      console.log(`${data.author}: ${data.text}`);
    });

    chat.on('presence-update', (data) => {
      console.log(`${data.metadata?.name} is ${data.status}`);
    });
    ```
  </Tab>

  <Tab title="Multiplayer Game">
    ```typescript theme={null}
    import { createGame } from '@klastra/ksync';

    // Game with low-latency updates
    const game = createGame('game-123', {
      performance: { batchSize: 50, batchDelay: 5 }
    });

    // Player actions
    await game.send('player-move', {
      playerId: 'player-1',
      x: 100,
      y: 200,
      timestamp: Date.now()
    });

    // Real-time game state
    game.on('player-move', (data) => {
      updatePlayerPosition(data.playerId, data.x, data.y);
    });

    // Player presence
    await game.setPresence({
      status: 'playing',
      metadata: { level: 5, score: 1200 }
    });
    ```
  </Tab>

  <Tab title="AI Application">
    ```typescript theme={null}
    import { createAI } from '@klastra/ksync';

    // AI with streaming responses
    const ai = createAI('assistant', {
      features: { streaming: true }
    });

    // Listen for streaming chunks
    ai.on('stream-chunk', (data) => {
      process.stdout.write(data.data); // Live AI response
    });

    ai.on('stream-end', (data) => {
      console.log('\nResponse complete!');
    });

    // Start AI response stream
    await ai.startStream('response-1');
    await ai.streamChunk('response-1', { data: 'Hello! ' });
    await ai.streamChunk('response-1', { data: 'How can I help?' });
    await ai.endStream('response-1');
    ```
  </Tab>

  <Tab title="Todo Application">
    ```typescript theme={null}
    import { createTodos } from '@klastra/ksync';

    // Todo app with offline persistence
    const todos = createTodos({
      offline: { persistence: true, queueSize: 5000 }
    });

    // Create todo
    await todos.send('todo-created', {
      id: 'todo-1',
      title: 'Buy groceries',
      completed: false,
      createdAt: Date.now()
    });

    // Listen for changes
    todos.on('todo-created', (data) => {
      addTodoToUI(data);
    });

    todos.on('todo-updated', (data) => {
      updateTodoInUI(data);
    });
    ```
  </Tab>
</Tabs>

## Real-time Chat Example

Let's build a complete chat application in under 50 lines:

```typescript theme={null}
import { createChat } from '@klastra/ksync';

// Create chat instance
const chat = createChat('general', {
  serverUrl: 'ws://localhost:8080',  // Optional - works offline without server
  features: { presence: true }
});

// Set user info
await chat.setPresence({
  status: 'online',
  metadata: { 
    name: 'Alice',
    avatar: 'https://api.dicebear.com/7.x/avataaars/svg?seed=Alice'
  }
});

// UI Elements (assuming HTML exists)
const messagesDiv = document.getElementById('messages');
const messageInput = document.getElementById('messageInput');
const sendButton = document.getElementById('sendButton');
const presenceDiv = document.getElementById('presence');

// Send message function
async function sendMessage() {
  const text = messageInput.value.trim();
  if (!text) return;

  await chat.send('message', {
    text,
    author: 'Alice',
    timestamp: Date.now(),
    id: `msg-${Date.now()}`
  });

  messageInput.value = '';
}

// Listen for messages
chat.on('message', (data) => {
  const messageEl = document.createElement('div');
  messageEl.innerHTML = `
    <strong>${data.author}</strong>: ${data.text}
    <small>(${new Date(data.timestamp).toLocaleTimeString()})</small>
  `;
  messagesDiv.appendChild(messageEl);
  messagesDiv.scrollTop = messagesDiv.scrollHeight;
});

// Listen for presence updates
chat.on('presence-update', (data) => {
  updatePresenceUI();
});

function updatePresenceUI() {
  const presence = chat.getPresence();
  presenceDiv.innerHTML = presence
    .map(p => `<span class="user ${p.status}">${p.metadata?.name || p.userId}</span>`)
    .join('');
}

// Event listeners
sendButton.addEventListener('click', sendMessage);
messageInput.addEventListener('keypress', (e) => {
  if (e.key === 'Enter') sendMessage();
});

// Initial presence update
updatePresenceUI();
```

## React Integration

For React applications, kSync v0.2 provides simple state integration:

```tsx theme={null}
import React, { useState, useEffect } from 'react';
import { createChat } from '@klastra/ksync';

function ChatApp() {
  const [chat] = useState(() => createChat('my-room'));
  const [messages, setMessages] = useState([]);
  const [presence, setPresence] = useState([]);

  useEffect(() => {
    // Listen for messages
    chat.on('message', (data) => {
      setMessages(prev => [...prev, data]);
    });

    // Listen for presence
    chat.on('presence-update', () => {
      setPresence(chat.getPresence());
    });

    // Set initial presence
    chat.setPresence({
      status: 'online',
      metadata: { name: 'React User' }
    });

    return () => {
      chat.disconnect();
    };
  }, [chat]);

  const sendMessage = async (text: string) => {
    await chat.send('message', {
      text,
      author: 'React User',
      timestamp: Date.now(),
      id: `msg-${Date.now()}`
    });
  };

  return (
    <div>
      <div>
        <h3>Online ({presence.length})</h3>
        {presence.map(p => (
          <div key={p.userId}>{p.metadata?.name || p.userId}</div>
        ))}
      </div>
      
      <div>
        <h3>Messages</h3>
        {messages.map(msg => (
          <div key={msg.id}>
            <strong>{msg.author}</strong>: {msg.text}
          </div>
        ))}
      </div>
      
      <input 
        onKeyPress={e => e.key === 'Enter' && sendMessage(e.target.value)}
        placeholder="Type a message..."
      />
    </div>
  );
}
```

## AI Streaming Example

Build a real-time AI chat with streaming responses:

```typescript theme={null}
import { createAI } from '@klastra/ksync';

const ai = createAI('gpt-assistant', {
  features: { streaming: true }
});

// Simple streaming chat interface
class AIChat {
  private currentResponse = '';
  private responseElement: HTMLElement;

  constructor(responseElementId: string) {
    this.responseElement = document.getElementById(responseElementId);
    this.setupListeners();
  }

  private setupListeners() {
    // Listen for streaming chunks
    ai.on('stream-chunk', (data) => {
      this.currentResponse += data.data;
      this.responseElement.textContent = this.currentResponse;
    });

    // Response complete
    ai.on('stream-end', (data) => {
      console.log('AI response complete');
      // Save to message history, etc.
    });
  }

  async askQuestion(question: string) {
    // Clear previous response
    this.currentResponse = '';
    this.responseElement.textContent = 'AI is thinking...';

    // Simulate AI response stream
    const responseId = `response-${Date.now()}`;
    await ai.startStream(responseId);

    // Simulate streaming response (replace with real AI API)
    const words = [
      'I understand your question. ',
      'Let me think about this carefully. ',
      'Based on my knowledge, ',
      'I would recommend the following approach...'
    ];

    for (const word of words) {
      await new Promise(resolve => setTimeout(resolve, 500));
      await ai.streamChunk(responseId, { data: word });
    }

    await ai.endStream(responseId);
  }
}

// Usage
const chat = new AIChat('ai-response');
document.getElementById('ask-button').onclick = () => {
  const question = document.getElementById('question-input').value;
  chat.askQuestion(question);
};
```

## Advanced Configuration

For production applications, you can customize kSync extensively:

```typescript theme={null}
import { createKSync } from '@klastra/ksync';

const ksync = createKSync({
  // Connection
  serverUrl: 'wss://your-server.com/ws',
  room: 'my-app',
  userId: 'user-123',

  // Authentication
  auth: {
    token: 'your-jwt-token',
    type: 'bearer'
  },

  // Performance tuning
  performance: {
    batchSize: 200,         // Higher for throughput
    batchDelay: 5,          // Lower for real-time
    materializationCaching: true,
    compressionThreshold: 1024
  },

  // Offline support
  offline: {
    enabled: true,
    queueSize: 10000,
    persistence: true,
    syncOnReconnect: true
  },

  // Features
  features: {
    presence: true,
    streaming: true,
    encryption: false
  },

  // Production debugging
  debug: {
    events: false,      // Disable in production
    performance: true   // Monitor performance
  }
});
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Performance Benchmarks" icon="chart-line" href="/benchmarks">
    See how kSync delivers 600k+ ops/sec performance
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/core">
    Explore all available methods and configuration options
  </Card>

  <Card title="Factory Functions Guide" icon="magic-wand" href="/guides/factory-functions">
    Learn about optimized presets for different use cases
  </Card>

  <Card title="Production Deployment" icon="rocket" href="/guides/production">
    Deploy kSync for enterprise-scale applications
  </Card>
</CardGroup>

***

**You now have a real-time sync engine running in under 2 minutes!** kSync v0.2's smart defaults mean you can focus on building features, not configuring infrastructure.