🟢 Dialogue

    Dialogue Configuration

    The main configuration object passed to createDialogue.

    Full Configuration Example

    import { Hono } from "hono";
import { createDialogue, defineEvent } from "./dialogue";
import { z } from "zod";

const Message = defineEvent("message", {
  schema: z.object({ text: z.string(), senderId: z.string() }),
  history: { enabled: true, limit: 100 }, // Enable history storage
});

const app = new Hono();

// Add HTTP routes
app.get("/health", (c) => c.json({ status: "ok" }));

const dialogue = createDialogue({
  port: 3000,
  app, // Use existing Hono app
  rooms: {
    chat: {
      name: "Chat",
      events: [Message],
      defaultSubscriptions: ["message"],
      syncHistoryOnJoin: true, // Auto-send history on join
    },
  },
  hooks: {
    clients: {
      onConnected: async (client) => {
        // Called when a client connects
        console.log(`Client ${client.userId} connected`);

        // Auto-join rooms based on user permissions
        const userRooms = await getUserRooms(client.userId);
        for (const roomId of userRooms) {
          client.join(roomId);
        }

        // Send initial data
        client.send("sync", { timestamp: Date.now() });
      },
      onDisconnected: (client) => {
        console.log(`Client ${client.userId} disconnected`);
      },
    },
  },
});

    Configuration Options

    PropertyTypeRequiredDescription
    portnumberNoPort to run server on. Defaults to 3000
    appHonoNoExisting Hono app to attach to. Creates new one if not provided
    roomsRecord<string, RoomConfig>YesRoom configurations keyed by room ID
    hooksHooksConfigNoLifecycle hooks for clients, rooms, and events
    loggerLoggerNoCustom logger implementation. Uses console logger if not provided
    corsCorsConfig | booleanNoCORS configuration. Defaults to allowing all origins
    runtime"bun" | "node"NoRuntime for the HTTP server and Socket.IO engine. Auto-detected if not specified

    CORS Configuration

    By default, Dialogue enables CORS for all origins, making it easy to develop with frontend and backend on different ports. CORS is applied to both HTTP requests (Socket.IO polling) and WebSocket connections.

    // Default behavior - allows all origins
const dialogue = createDialogue({
  rooms: { /* ... */ },
});

// Restrict to specific origins
const dialogue = createDialogue({
  rooms: { /* ... */ },
  cors: {
    origin: "https://myapp.com",
    credentials: true,
  },
});

// Allow multiple origins
const dialogue = createDialogue({
  rooms: { /* ... */ },
  cors: {
    origin: ["https://myapp.com", "https://admin.myapp.com"],
  },
});

// Disable CORS (same-origin only)
const dialogue = createDialogue({
  rooms: { /* ... */ },
  cors: false,
});

    CorsConfig Options:

    PropertyTypeDefaultDescription
    originstring | string[] | booleantrueAllowed origins. Use true for all origins
    methodsstring[]["GET", "POST"]Allowed HTTP methods
    credentialsbooleantrueWhether to allow credentials (cookies, auth headers)

    Runtime Selection

    Dialogue supports both Bun and Node.js runtimes via a runtime adapter pattern. By default, the runtime is auto-detected by checking for globalThis.Bun. You can override this with the runtime option.

    // Auto-detect (default) — uses Bun if available, falls back to Node.js
const dialogue = createDialogue({
  rooms: { /* ... */ },
});

// Explicitly use Bun
const dialogue = createDialogue({
  rooms: { /* ... */ },
  runtime: "bun",
});

// Explicitly use Node.js
const dialogue = createDialogue({
  rooms: { /* ... */ },
  runtime: "node",
});

    Runtime behavior:

    RuntimeHTTP ServerSocket.IO EngineNotes
    "bun"Bun.serve()@socket.io/bun-engineNative Bun performance
    "node"http.createServer()Built-in engine.ioUses @hono/node-server to bridge Hono's fetch API

    Both runtimes produce identical behavior from the client's perspective. The adapter pattern ensures all Dialogue features (rooms, events, hooks, CORS) work the same regardless of runtime.

    DialogueContext

    All authentication and event hooks receive a DialogueContext object providing global runtime awareness:

    interface DialogueContext {
  io: Server;                              // Socket.IO server instance
  clients: Record<string, ConnectedClient>; // All connected clients by ID
  rooms: Record<string, Room>;             // All active rooms by ID
}

    Example usage in hooks:

    beforeEach: ({ context, roomId, message }) => {
  // Access all clients
  const totalClients = Object.keys(context.clients).length;
  
  // Access specific room
  const room = context.rooms[roomId];
  
  // Access Socket.IO server
  context.io.emit("global-event", { data: "..." });
  
  return Ok(message);
}

    See Also