@sourceregistry/sveltekit-actionbus

Typed, component-first live updates for SvelteKit. ActionBus gives an app one shared WebSocket connection, typed channel subscriptions, authorized server broadcasts, and Svelte stores for client-side reactive state.

V1 is intentionally server-to-client for business data. Client WebSocket messages are limited to subscribe/unsubscribe control messages; mutations should remain SvelteKit actions or endpoints.

Features

• One root Svelte 5 <ActionBus> provider
• Typed channels and per-channel events through App.ActionEvents
• Runtime channel/event-name validation generated by the Vite plugin
• Authorized server-side subscriptions
• Reference-counted client subscriptions
• Svelte readable stores, subscription-scoped errors, and reducer-based eventStore
• Best-effort delivery with reconnect and automatic resubscribe

Installation

npm install @sourceregistry/sveltekit-actionbus

Setup

Register the Vite plugin.

// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
import { actionbus } from '@sourceregistry/sveltekit-actionbus/vite';

export default defineConfig({
    plugins: [sveltekit(), actionbus()]
});

Declare the channels and events your app can use.

// src/app.d.ts
declare global {
    namespace App {
        interface ActionEvents {
            'project:${string}': {
                'task.updated': { id: string; title: string };
                'task.deleted': { id: string };
            };

            'user:${string}:notifications': {
                'notification.created': { id: string; message: string };
            };
        }
    }
}

export {};

Client Usage

Mount one bus near the root of the app.

<!-- src/routes/+layout.svelte -->
<script lang="ts">
    import ActionBus from '@sourceregistry/sveltekit-actionbus/ActionBus.svelte';

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

<ActionBus url="/actionbus">
    {@render children()}
</ActionBus>

Subscribe from descendants with the module export from ActionBus.svelte.

<script lang="ts">
    import { subscribe } from '@sourceregistry/sveltekit-actionbus/ActionBus.svelte';

    const actionbus = subscribe('project:123', 'user:me:notifications');
    const project = actionbus.channel('project:123');
    const errors = actionbus.errors;

    const tasks = project.eventStore(data.tasks, {
        'task.updated': (tasks, message) => {
            return upsert(tasks, message.event.payload);
        },
        'task.deleted': (tasks, message) => {
            return tasks.filter((task) => task.id !== message.event.payload.id);
        }
    });
</script>

subscribe(...) can retain multiple channels with one shared connection. Use subscription.channel(channel) when reducers should be scoped to one channel, especially when different channels can emit the same event name.

You can also use the convenience component.

<script lang="ts">
    import ActionSubscription from '@sourceregistry/sveltekit-actionbus/ActionSubscription.svelte';
</script>

<ActionSubscription channels={['project:123'] as const}>
    {#snippet children({ events, errors, eventStore, state })}
        <!-- render with the subscription stores -->
    {/snippet}
</ActionSubscription>

Server Usage

Create one server-side bus and import it from server code that broadcasts events.

// src/lib/server/actionbus.ts
import { createActionBus } from '@sourceregistry/sveltekit-actionbus/server';

export const actionbus = createActionBus({
    path: '/actionbus',
    authorize: async ({ channel, request }) => {
        return canSubscribe(request, channel);
    }
});

Broadcast typed events to subscribed clients.

actionbus.broadcast('project:123', {
    type: 'task.updated',
    payload: { id: 't1', title: 'New title' }
});

Local Example

This repository includes a runnable showcase under src/routes.

npm run dev

Open the local app in two browser tabs. The page subscribes to project:demo; submitting the form in one tab broadcasts a typed task.updated event to the other tab through the shared ActionBus socket.

Deployment Notes

ActionBus uses WebSockets through @sourceregistry/sveltekit-websockets. It needs a SvelteKit deployment target that supports persistent WebSocket upgrades. Serverless or edge-only platforms that do not support WebSocket upgrades are out of scope for V1.