svelte-socket

WebSocket wrapper for Svelte 5 using runes.

Overview

This library provides:

• SvelteSocket - WebSocket wrapper class with reactive state properties (connectionStatus, sentMessages, receivedMessages)
• SocketProvider - Context provider component that instantiates SvelteSocket and makes it available to child components
• Debugger - UI panel component showing connection status, sent messages, and received messages
• useSocket() - Hook to access socket instance from context

Features

• Constructor accepts configuration object with URL and optional callbacks (onMessage, onOpen, onClose, onError)
• Optional debug logging via debug flag
• Auto-reconnection with configurable delay and max attempts
• Reactive message history (sent and received)
• All state properties use Svelte 5 $state runes
• TypeScript support

Installation

npm install svelte-socket

Usage

In parent components including +page.svelte or +layout.svelte...

<script>
	import { SvelteSocket } from 'svelte-socket';

	// Callbacks can be added on construction...
	const socket = new SvelteSocket({
		url: 'ws://localhost:8080',
		onOpen: () => console.log('Hello, server!')
	});
	const isConnected = $derived(socket.connectionStatus === WebSocket.OPEN);

	// ...or later using addEventListener
	socket.addEventListener('message', (event) => {
		console.log(event.data);
	});

	socket.sendMessage('text');
</script>

<SocketProvider {svelteSocket}>
	{@render children()}
</SocketProvider>

In any child component...

<script>
	import { useSocket } from 'svelte-socket';
	let { children } = $props();
	const socket = useSocket()
	let isConnected = $derived(socket.connectionStatus === WebSocket.OPEN);
	let receivedMessages = $derived(socket.receivedMessages)
</script>

<p>{isConnected}</p>
{#each receivedMessages as msg, i}
	<p>{msg.origin}<p>
{/each}

API

SvelteSocket

Constructor

new SvelteSocket(options: SocketConstructorArgs)

Options:

| Property | Type | Required | Description | | ------------------- | ------------------------------- | -------- | ------------------------------------------------------------------------- | | url | string | Yes | WebSocket server URL | | onMessage | (event: MessageEvent) => void | No | Called when message received | | onOpen | (event: Event) => void | No | Called when connection opens | | onClose | (event: CloseEvent) => void | No | Called when connection closes | | onError | (event: Event) => void | No | Called on error | | debug | boolean | No | Enable console logging (default: false) | | reconnectOptions | ReconnectOptions | No | Auto-reconnection config | | maxMessageHistory | number | No | Max messages to keep in history (default: 50). Set to 0 for unlimited |

ReconnectOptions:

| Property | Type | Description | | ------------- | --------- | ------------------------------------- | | enabled | boolean | Enable auto-reconnection | | delay | number | Milliseconds before reconnect attempt | | maxAttempts | number | Maximum reconnection attempts |

Example:

const socket = new SvelteSocket({
	url: 'ws://localhost:8080',
	debug: true,
	maxMessageHistory: 100, // Keep last 100 messages (default: 50)
	reconnectOptions: {
		enabled: true,
		delay: 1000,
		maxAttempts: 5
	},
	onMessage: (event) => console.log(event.data),
	onOpen: () => console.log('connected'),
	onClose: () => console.log('disconnected')
});

Properties

| Property | Type | Description | | ------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | connectionStatus | WebSocket['readyState'] | Connection state: 0 (CONNECTING), 1 (OPEN), 2 (CLOSING), 3 (CLOSED) | | sentMessages | Array<{message: string \| ArrayBuffer \| Blob \| ArrayBufferView, timestamp: number}> | Sent message history (newest first, via unshift). Auto-trimmed to maxMessageHistory | | receivedMessages | Array<{message: MessageEvent}> | Received message history (newest first, via unshift). Auto-trimmed to maxMessageHistory | | maxMessageHistory | number | Maximum number of messages to keep in history (default: 50, readonly) |

Example:

<script>
	const socket = new SvelteSocket({ url: 'ws://localhost:8080' });

	const connectionStatus = $derived(socket.connectionStatus);
	const sentMessages = $derived(socket.sentMessages);
	const receivedMessages = $derived(socket.receivedMessages);
</script>

{#if connectionStatus === WebSocket.OPEN}
	<p>Open</p>
{:else if connectionStatus === WebSocket.CONNECTING}
	<p>Connecting</p>
{:else}
	<p>Closed</p>
{/if}

<p>{sentMessages.length} sent</p>
<p>{receivedMessages.length} received</p>

{#each receivedMessages as { message }}
	<div>{message.data}</div>
{/each}

Methods

addEventListener(event, callback)

addEventListener(
	event: 'message' | 'close' | 'open' | 'error',
	callback: (event: MessageEvent | CloseEvent | Event) => void
): void

Adds event listener to WebSocket. The callback type is automatically inferred based on the event type:

• 'message' → (event: MessageEvent) => void
• 'close' → (event: CloseEvent) => void
• 'open' → (event: Event) => void
• 'error' → (event: Event) => void

Throws if socket not connected.

socket.addEventListener('message', (event) => {
	console.log(event.data); // event is typed as MessageEvent
});

removeEventListener(event, callback)

removeEventListener(
	event: 'message' | 'close' | 'open' | 'error',
	callback: (event: MessageEvent | CloseEvent | Event) => void
): void

Removes event listener. Callback types match addEventListener.

const handler = (event) => console.log(event.data);
socket.addEventListener('message', handler);
socket.removeEventListener('message', handler);

sendMessage(message)

sendMessage(message: string | ArrayBuffer | Blob | ArrayBufferView): void

Sends a text or binary message through the WebSocket. Supports strings, ArrayBuffer, Blob, TypedArray, and DataView. Stores in sentMessages array. Throws if not connected or not in OPEN state.

Example:

// Send text
socket.sendMessage('Hello, server!');
socket.sendMessage(JSON.stringify({ type: 'ping' }));

// Send binary data
const buffer = new Uint8Array([1, 2, 3, 4]);
socket.sendMessage(buffer);

clearSentMessages()

clearSentMessages(): void

Clears sentMessages array.

socket.clearSentMessages();

clearReceivedMessages()

clearReceivedMessages(): void

Clears receivedMessages array.

socket.clearReceivedMessages();

removeSocket()

removeSocket(): void

Closes WebSocket connection. Clears message history. Prevents reconnection.

socket.removeSocket();

SocketProvider

Context provider component that makes a socket instance available to child components.

Props:

| Property | Type | Required | Description | | -------------- | -------------- | -------- | --------------------------------------------------- | | url | string | Yes* | WebSocket server URL (automatically creates socket) | | svelteSocket | SvelteSocket | Yes* | Pre-configured SvelteSocket instance | | children | Snippet | No | Child components |

*At least one of url or svelteSocket must be provided. If both are provided, svelteSocket takes precedence.

Basic Usage:

The simplest way to use the provider is to pass a url, which automatically creates a SvelteSocket for you:

<script>
	import { SocketProvider } from 'svelte-socket';

	let { children } = $props();
</script>

<SocketProvider url="ws://localhost:8080">
	{@render children()}
</SocketProvider>

Custom Socket Configuration:

You can also create your own SvelteSocket with custom callbacks and options, then pass it to the provider:

<script>
	import { SocketProvider, SvelteSocket } from 'svelte-socket';

	let { children } = $props();

	const svelteSocket = new SvelteSocket({
		url: 'ws://localhost:8080',
		debug: true,
		reconnectOptions: {
			enabled: true,
			delay: 1000,
			maxAttempts: 5
		},
		onMessage: (event) => {
			console.log('Received:', event.data);
		},
		onOpen: () => {
			console.log('Connected!');
		}
	});
</script>

<SocketProvider {svelteSocket}>
	{@render children()}
</SocketProvider>

useSocket()

useSocket(): SvelteSocket

Returns socket instance from context.

Throws if not used within SocketProvider.

Example:

<script>
	import { useSocket } from 'svelte-socket';

	const socket = useSocket();
</script>

Debugger

Debug UI component. Shows connection status, sent messages, received messages.

Props:

| Property | Type | Required | | -------- | -------------- | -------- | | socket | SvelteSocket | Yes |

Example:

<script>
	import { SvelteSocket, Debugger } from 'svelte-socket';

	const socket = new SvelteSocket({ url: 'ws://localhost:8080' });
</script>

<Debugger {socket} />

Displays:

• Connection state (CONNECTING/OPEN/CLOSING/CLOSED)
• Message counts (sent/received)
• Sent message history with timestamps
• Received message history with data

Styling Requirements:

This component requires Tailwind CSS. You must configure Tailwind to scan the package files:

Tailwind v4:

/* app.css */
@import 'tailwindcss';
@source '../node_modules/@hardingjam/svelte-socket/dist/**/*.svelte';

Tailwind v3:

// tailwind.config.js
export default {
	content: [
		'./src/**/*.{html,js,svelte,ts}',
		'./node_modules/@hardingjam/svelte-socket/dist/**/*.svelte'
	]
	// ... rest of config
};

Context Functions

setSocket(socket)

setSocket(socket: SvelteSocket): void

Sets socket in Svelte context. Used by SocketProvider.

getSocketContext()

getSocketContext(): SvelteSocket

Gets socket from context. Throws if not found.

Examples

Basic

<script>
	import { SvelteSocket } from 'svelte-socket';

	const socket = new SvelteSocket({ url: 'ws://localhost:8080' });

	socket.addEventListener('message', (event) => {
		console.log(event.data);
	});

	function send() {
		socket.sendMessage('test');
	}
</script>

<button onclick={send}>Send</button>

Auto-reconnect

<script>
	import { SvelteSocket } from 'svelte-socket';

	const socket = new SvelteSocket({
		url: 'ws://localhost:8080',
		debug: true,
		reconnectOptions: {
			enabled: true,
			delay: 1000,
			maxAttempts: 5
		}
	});
</script>

JSON Messages

<script>
	import { SvelteSocket } from 'svelte-socket';

	const socket = new SvelteSocket({ url: 'ws://localhost:8080' });

	socket.addEventListener('message', (event) => {
		const data = JSON.parse(event.data);

		if (data.type === 'ping') {
			socket.sendMessage(JSON.stringify({ type: 'pong' }));
		}
	});
</script>

Message History

<script>
	import { SvelteSocket } from 'svelte-socket';

	const socket = new SvelteSocket({ url: 'ws://localhost:8080' });
	const sentMessages = $derived(socket.sentMessages);
	const receivedMessages = $derived(socket.receivedMessages);

	let input = $state('');

	function send() {
		if (input) {
			socket.sendMessage(input);
			input = '';
		}
	}
</script>

<input bind:value={input} />
<button onclick={send}>Send</button>

<h3>Sent ({sentMessages.length})</h3>
{#each sentMessages as { message, timestamp }}
	<div>
		{new Date(timestamp).toLocaleTimeString()}: {message}
	</div>
{/each}

<h3>Received ({receivedMessages.length})</h3>
{#each receivedMessages as { message }}
	<div>{message.data}</div>
{/each}

<button onclick={() => socket.clearSentMessages()}>Clear</button>

With Provider

<!-- +layout.svelte -->
<script>
	import { SocketProvider } from 'svelte-socket';

	let { children } = $props();
</script>

<SocketProvider url="ws://localhost:8080">
	{@render children()}
</SocketProvider>

<!-- +page.svelte -->
<script>
	import { useSocket } from 'svelte-socket';

	const socket = useSocket();

	socket.addEventListener('message', (event) => {
		console.log(event.data);
	});
</script>

TouchDesigner Integration

Broadcast to all connected clients:

# TouchDesigner Text DAT
def broadcast():
    webServer = op('webserver1')
    clients = webServer.clients

    for client in clients:
        webServer.webSocketSendText(client, "message")

    print(f"Sent to {len(clients)} clients")

Requirements

• Svelte 5.0+
• WebSocket support

License

MIT