@korajs/server

Self-hosted sync server for Kora.js applications. Accepts WebSocket and HTTP connections from Kora clients, stores operations, and relays changes between devices. Supports multiple storage backends via Drizzle ORM.

Install

pnpm add @korajs/server

Quick Start

import { createKoraServer, MemoryServerStore } from '@korajs/server'

const server = createKoraServer({
  store: new MemoryServerStore(),
  port: 4567,
})

await server.start()
// Kora sync server listening on ws://localhost:4567

Production Setup with PostgreSQL

import { createKoraServer, PostgresServerStore, TokenAuthProvider } from '@korajs/server'

const server = createKoraServer({
  store: new PostgresServerStore({
    connectionString: process.env.DATABASE_URL,
  }),
  port: 4567,
  auth: new TokenAuthProvider({
    validate: async (token) => {
      // Validate JWT or session token
      const user = await verifyToken(token)
      return { userId: user.id, scopes: { todos: { userId: user.id } } }
    },
  }),
})

await server.start()

Storage Backends

| Backend | Package | Use Case | |---------|---------|----------| | MemoryServerStore | Built-in | Development and testing | | SqliteServerStore | Built-in | Small deployments, prototyping | | PostgresServerStore | Built-in | Production |

Mixed Auth (Authenticated + Anonymous)

For apps where some users are authenticated and others are anonymous:

import { MixedAuthProvider } from '@korajs/server'

const server = createKoraServer({
  store: serverStore,
  auth: new MixedAuthProvider({
    primary: authRoutes.toSyncAuthProvider(),
    anonymousScopes: { responses: {} },
  }),
})

Materialized Collections

Enable server-side queries on your data:

await store.setSchema(schema)

// Query with filters
const forms = await store.queryCollection('forms', {
  where: { status: 'published' },
  limit: 10,
})

// Count records
const count = await store.countCollection('responses', { formId: 'abc' })

Configuration

createKoraServer({
  store: serverStore,         // Required: storage backend
  port: 4567,                 // Default: 4567
  auth: authProvider,         // Optional: authentication provider
  batchSize: 1000,            // Optional: max operations per sync batch
  maxConnections: 0,          // Optional: 0 = unlimited
})

License

MIT

See the full documentation for guides, API reference, and examples.