realtime

A chat, a notification bell, a dashboard that updates by itself: all of them need the server to push to open screens. kitr/realtime gives you typed channels that work the same over three transports, chosen in config/realtime.ts: WebSockets (default), Socket.IO, or server-sent events.

Install

kitr add realtime

This installs @kitr/realtime (and the server package if missing), writes config/realtime.ts, app/channels/example.ts, server/realtime.ts, attaches the realtime server in server/main.ts, and in React apps writes app/realtime.ts with the client connection.

Define a channel once

// app/channels/chat.ts
import { defineChannel } from 'kitr/realtime'

export const chatChannel = defineChannel<{ room: string }>({
  name: 'chat',
  events: {
    message: { effects: (_m: Message, { room }) => ({ invalidate: [['messages', room]] }) },
  },
  authorize: (params, ctx) => !!ctx.user,
})

Emit from the server

// server/controllers/messages_controller.ts
import { realtime } from '#server/realtime'

realtime.use(chatChannel, { room }).emit('message', message)

Subscribe in a component

import { useChannel } from 'kitr/realtime/react'
import { realtime } from '#app/realtime'

function Room({ room }: { room: string }) {
  useChannel(realtime(), chatChannel, { room })
  // events apply their `effects` to the query cache, so useQuery(['messages', room]) refreshes
}

channel(transport, def).subscription() is also a kitr SubscriptionContract, so useSubscription() from query works with it directly.

Transports

The channel definitions, the server emit() and the hooks do not change between them.