syncedstate

svelte-synced-state

Easily sync Go backend state with Svelte over WebSockets.

This package keeps typed state objects in a Go process and mirrors them into Svelte 5 $state objects. The backend exports a standard net/http WebSocket handler. The frontend subscribes to named state objects, applies server snapshots and updates, and can sync local changes back as full-value replacements.

This project is based on the same state-syncing model as tauri-svelte-synced-store, adapted from Tauri events to a standard Go WebSocket backend.

Go

package main

import (
	"context"
	"log"
	"net/http"

	syncedstate "github.com/synthlabs/svelte-synced-state"
)

type InternalState struct {
	Authenticated bool   `json:"authenticated"`
	Name          string `json:"name"`
}

func main() {
	manager := syncedstate.NewManager()
	internal, err := syncedstate.Define(manager, "InternalState", InternalState{})
	if err != nil {
		log.Fatal(err)
	}

	http.Handle("/synced-state", manager.Handler(
		syncedstate.WithOriginPatterns("http://localhost:*"),
	))

	http.HandleFunc("/login", func(w http.ResponseWriter, r *http.Request) {
		err := internal.Update(r.Context(), func(state *InternalState) {
			state.Authenticated = true
			state.Name = r.FormValue("name")
		})
		if err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}
		w.WriteHeader(http.StatusNoContent)
	})

	log.Fatal(http.ListenAndServe(":8080", nil))
}

Handler options can tune the websocket send buffer. By default, a client is closed when its send buffer fills. Use WithBlockOnFullBuffer to apply backpressure to the goroutine sending the update instead:

http.Handle("/synced-state", manager.Handler(
	syncedstate.WithSendBuffer(128),
	syncedstate.WithBlockOnFullBuffer(),
))

For longer critical sections, use the lower-level lock handle:

locked, err := internal.Lock(context.Background())
if err != nil {
	return err
}
defer locked.Unlock()

locked.Value().Authenticated = true
locked.Value().Name = "Jerod"
return locked.Sync(context.Background())

Svelte

<script lang="ts">
	import { SyncedState } from 'svelte-synced-state';

	type InternalState = {
		authenticated: boolean;
		name: string;
	};

	const internal = new SyncedState<InternalState>('InternalState', {
		authenticated: false,
		name: ''
	});

	async function login(event: Event) {
		event.preventDefault();
		await internal.sync();
		await fetch('/login', {
			method: 'POST',
			body: new URLSearchParams({ name: internal.obj.name })
		});
	}
</script>

{#if internal.obj.authenticated}
	<h1>Welcome {internal.obj.name}</h1>
{/if}

<form onsubmit={login}>
	<input bind:value={internal.obj.name} />
	<button type="submit">Log in</button>
</form>

Protocol

The WebSocket transport uses JSON envelopes:

{ "type": "subscribe", "id": "1", "name": "InternalState" }

{ "type": "update", "name": "InternalState", "version": 2, "value": { "authenticated": true, "name": "Jerod" } }

{ "type": "set", "id": "2", "name": "InternalState", "version": 3, "value": { "authenticated": false, "name": "" } }

Supported message types are subscribe, unsubscribe, snapshot, set, update, and error. Snapshots and updates carry the current server-assigned version. Frontend set messages carry the next expected version, and stale writes receive a snapshot with the latest value/version plus an error string. V1 syncs full JSON values, not partial patches.

Development

pnpm --dir ui install
sh scripts/check.sh