hooks.ws.js

The WebSocket hooks file at src/hooks.ws.js (or .ts) controls the WebSocket lifecycle. It’s required for svelte-realtime to work.

Minimal setup

// src/hooks.ws.js
import { createMessage } from 'svelte-realtime/server';

export function upgrade() {
  return { id: crypto.randomUUID() };
}

export const message = createMessage();

Available hooks

upgrade({ cookies })

Runs on every new WebSocket connection. Return user data to attach, or false to reject.

export function upgrade({ cookies }) {
  const session = validateSession(cookies.session_id);
  if (!session) return false;
  return { id: session.userId, name: session.name };
}

message

Routes incoming WebSocket messages to your src/live/ functions. Create it with createMessage():

import { createMessage } from 'svelte-realtime/server';

export const message = createMessage({
  async beforeExecute(ws, rpcPath) {
    // Rate limiting, logging, etc.
  }
});

open(ws, { platform })

Fires when a WebSocket connection is fully established.

subscribe(ws, topic, ctx)

Fires when a client subscribes to a stream topic.

unsubscribe(ws, topic, ctx)

Fires when a client’s subscription count for a topic reaches zero.

close(ws, ctx)

Fires when the WebSocket closes (tab closed, network drop, etc).

Custom message handling

When you need to mix RPC with custom WebSocket messages, use onUnhandled or drop to handleRpc directly.

onUnhandled

Pass onUnhandled to createMessage to handle non-RPC messages (binary data, custom protocols, etc.):

export const message = createMessage({
  onUnhandled(ws, data, platform) {
    // handle non-RPC messages (binary data, custom protocols, etc.)
  }
});

handleRpc

For full control, use handleRpc directly and handle non-RPC messages yourself:

import { handleRpc } from 'svelte-realtime/server';

export function message(ws, { data, platform }) {
  if (handleRpc(ws, data, platform)) return;
  // your custom message handling
}

handleRpc returns true if the message was an RPC call, false otherwise. This lets you branch on the result and handle everything else however you want.

Progression

export { message } → createMessage({...}) → manual handleRpc. Start simple, add options when needed, drop to full control only if you have to.