Skip to main content

​
Prerequisites

Before installing kSync v0.2, make sure you have:

Node.js 18+

kSync v0.2 requires Node.js 18 or higher for modern JavaScript features

TypeScript (Recommended)

TypeScript provides excellent IntelliSense with 50+ configuration options

​
Package Installation

npm install @klastra/ksync
No dependencies required! kSync v0.2 works out of the box with smart defaults. Zod is optional for advanced schema validation.

​
Quick Start (30 seconds)

Get running instantly with factory functions: 
import { createKSync } from '@klastra/ksync';

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

// Send events
await ksync.send('message', { text: 'Hello world!' });

// Listen for events
ksync.on('message', (data) => console.log(data.text));

​
TypeScript Configuration

For the best experience with TypeScript, add these settings to your tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "jsx": "react-jsx"  // For React integration
  }
}

​
Environment Setup

​
Browser Environment

For browser applications, kSync v0.2 automatically configures optimal settings:
  • IndexedDB for local storage with memory fallback
  • Web Locks API for tab coordination
  • WebSocket for real-time sync
  • Smart batching for performance
import { createKSync } from '@klastra/ksync';

// Browser-optimized configuration
const ksync = createKSync({
  serverUrl: 'ws://localhost:8080', // Your WebSocket server
  // Storage automatically uses IndexedDB
});

​
Node.js Environment

For server-side or Node.js applications: 
import { createKSync } from '@klastra/ksync';

// Server-optimized configuration
const ksync = createKSync({
  storage: { type: 'memory' }, // Memory storage for servers
  sync: { enabled: false },    // Disable sync on server
});

​
Bun Environment

kSync v0.2 is optimized for Bun and works perfectly: 
import { createKSync } from '@klastra/ksync';

const ksync = createKSync({
  serverUrl: 'ws://localhost:8080',
  performance: { 
    batchSize: 200,  // Leverage Bun's performance
    batchDelay: 5    // Ultra-low latency
  }
});

​
Factory Functions

kSync v0.2 provides optimized presets for common use cases: 
import { createChat } from '@klastra/ksync';

// Optimized for chat with presence
const chat = createChat('room-name', {
  serverUrl: 'ws://localhost:8080'
});

await chat.setPresence({ 
  status: 'online', 
  metadata: { name: 'Alice' } 
});

​
Development Server Setup

​
Option 1: Use Built-in Server

kSync v0.2 includes a production-ready WebSocket server: 
# Clone for development
git clone https://github.com/0ni-x4/ksync.git
cd ksync

# Install dependencies
npm install

# Start the development server
npm run server

​
Option 2: Custom Server

Create your own high-performance WebSocket server: 
import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });
console.log('🚀 kSync server running on ws://localhost:8080');

wss.on('connection', (ws) => {
  console.log('📱 Client connected');

  ws.on('message', (data) => {
    // Broadcast to all other clients
    wss.clients.forEach((client) => {
      if (client !== ws && client.readyState === 1) {
        client.send(data);
      }
    });
  });
});

​
Performance Optimization

kSync v0.2 is production-ready with enterprise performance:
Benchmark Results:
  • 🎯 600k+ ops/sec with 500 concurrent clients
  • 🧠 2MB memory for 1000 clients + 10k events
  • 🌐 Network resilient - handles 10-200ms latency
  • ⚡ Sub-5ms event processing with optimized batching

​
Production Configuration

import { createKSync } from '@klastra/ksync';

const ksync = createKSync({
  // High-performance settings
  performance: {
    batchSize: 200,              // Higher throughput
    batchDelay: 5,               // Low latency
    materializationCaching: true, // Cache computed state
    compressionThreshold: 1024   // Compress large payloads
  },
  
  // Production features
  auth: {
    token: process.env.JWT_TOKEN,
    type: 'bearer'
  },
  
  // Monitoring
  debug: {
    events: false,         // Disable in production
    performance: true,     // Monitor metrics
    sync: false,
    storage: false
  },
  
  // Scaling
  offline: {
    queueSize: 10000,      // Large offline queue
    persistence: true      // Persist across restarts
  }
});

​
What’s Next?

Quick Start Guide

Build your first real-time app in 2 minutes

Factory Functions

Learn about optimized presets for different use cases

Performance Benchmarks

See detailed performance metrics and optimization tips

API Reference

Explore all 50+ configuration options and methods
kSync v0.2: Enterprise performance with developer-friendly APIs.