Dialogue

Event-based realtime communication library built on Socket.IO, Hono, and Bun

Installation

bun add dialogue-ts zod

Quick Start

Server Setup

// server.ts
import { createDialogue, defineEvent } from "dialogue-ts";
import { z } from "zod";

const Message = defineEvent("message", {
  schema: z.object({
    text: z.string(),
    senderId: z.string(),
  }),
});

const dialogue = createDialogue({
  rooms: {
    chat: {
      name: "Chat Room",
      events: [Message],
    },
  },
});

await dialogue.start();

Client Setup

// client.ts
import { createDialogueClient } from "dialogue-ts/client";

const client = createDialogueClient({
  url: "ws://localhost:3000",
  auth: { userId: "user-123" },
});

await client.connect();

const chat = await client.join("chat");

chat.on("message", (msg) => {
  console.log(msg.data.text);
});

chat.trigger("message", {
  text: "Hello!",
  senderId: "user-123",
});

Why Dialogue?

Event-based

Events help you handle any types of real-time interactions with a unified mental model, every interaction is an event

End-to-End Validation

You can define schemas for events using zod and validate to easily avoid mismatch bugs at runtime.

Powerful Hook System

Hook into various stages of the event lifecycle for custom logic and side effects.

Unified API

Server and clients share similar mental models accross interactions, so it's easy to reason about things.

Use Cases

Real-time Chat Applications

Define a Message event with Zod schema for text validation. Use user:joined and user:left events for presence tracking. Add a typing event to show when users are composing messages. All events are type-safe and automatically validated.

View chat examples →

Live Dashboards & Analytics

Create events like metrics:update and data:refresh with schemas that enforce data structure. Use Dialogue's room system to organize different dashboard views. Type inference ensures your frontend receives correctly-typed data from the server.

View dashboard examples →

Collaborative Tools

Define cursor:move, document:edit, and selection:change events to track user interactions. Dialogue's event system handles real-time broadcasting to all participants in a room while Zod validates each action's payload.

View collaboration examples →

Gaming & Multiplayer

Set up events like player:move, game:action, and lobby:join with strict schemas. Use rooms for game lobbies and matches. Dialogue validates player inputs server-side, preventing cheating and ensuring game state consistency.

View gaming examples →

Dialogue vs Bare Socket.IO

FeatureDialogueSocket.IO
Schema ValidationBuilt-in Zod integrationManual validation required
Type SafetyAutomatic type inference from schemasManual type definitions needed
Event SystemDeclarative event definitions with first-class supportString-based event names, no structure
Room ManagementConfigured upfront with type-safe joinsManual join/leave handling
Developer ExperienceUnified API, less boilerplateMore setup code, repetitive patterns
Runtime SafetyEvents validated against schemas at runtimeNo built-in validation