⚡ spark-html-websocket

Declarative WebSocket for spark-html — a live connection as a reactive store, with auto-reconnect, JSON parsing, status, and send(). Zero dependencies. No more hand-rolled connect/reconnect/parse/cleanup boilerplate in onMount.

import { ws } from 'spark-html-websocket';
ws('wss://stream.example.com/prices', { name: 'prices' });

<!-- any component -->
<p :hidden="prices.status !== 'open'">● live</p>
<h1>{prices.data?.btc}</h1>
<button onclick="{() => prices.send({ subscribe: 'btc' })}">Subscribe</button>
<script>
  const prices = useStore('prices');
</script>

Or fully declarative, the way the router declares routes:

<template ws="wss://stream.example.com/prices" store="prices"></template>
<script type="module">
  import { sockets } from 'spark-html-websocket';
  sockets();
</script>

Install

bun add spark-html-websocket

The store

| Key | Meaning | |-----|---------| | data | The last (post-filter) message — JSON-parsed when it looks like JSON. Survives reconnects. | | status | 'connecting' · 'open' · 'closed' · 'error' | | error | The last connection error, null when healthy. | | send(v) | Send a message; objects are stringified. Queued until the socket opens. | | close() | Deliberate close — never reconnects. | | open() | Re-open after a close() (or exhausted retries). |

Options

ws('wss://x.dev/feed', {
  name: 'feed',                          // store name (default "ws:x.dev/feed")
  json: true,                            // parse messages as JSON when possible
  filter: (d) => d.type === 'ticker',    // only these land in `data`
  onMessage: (d) => { store('candles').list.push(d); }, // feed ANY store
  reconnect: { retries: Infinity, base: 500, max: 10000 }, // backoff (ms); false disables
  protocols: ['v1'],
});

• Auto-reconnect — a dropped connection retries with exponential backoff (base·2ⁿ capped at max); data keeps rendering through the gap.
• Shared handles — ws() with the same name returns the existing store; two components never open two sockets.
• Prerender-safe — during spark-prerender builds (or anywhere WebSocket doesn't exist) the store is created inert with status: 'closed', so components render their fallback and the build never hangs. No guard needed.

Declarative attributes: ws (url), store (name), raw (skip JSON), retries / backoff / backoff-max (reconnect tuning, ms).

The Spark family

Small, single-purpose packages that share one philosophy: no compiler, no virtual DOM, no build step required — built for humans who love hand-writing their web apps. Add only what you use.

| Package | What it does | |---|---| | spark-html | The runtime — components, reactivity, stores, forms, scoped styles. ~14.4 kB gzip, 0 deps. | | spark-html-bun | Dev server, bundler & preview on Bun — scoped HMR, no-build dev, post-build pipeline. | | spark-html-router | <template route> routing — nested routes/layouts, route.query, active links. | | spark-html-theme | Dark/light/system theming in one line — persisted, no flash. | | spark-html-head | Reactive <title>/<meta> per route + a head store. | | spark-html-motion | Enter/leave transitions on if/each blocks — transition="fade|slide|scale". | | spark-html-devtools | In-page devtools — live stores, component tree, patch activity. | | spark-html-query | Declarative async data — a self-fetching store (loading/error/data/refetch). | | spark-html-persist | Persist stores to localStorage/sessionStorage in one line. | | spark-html-websocket | A WebSocket as a reactive store — auto-reconnect, JSON, send(). | | spark-prerender | Build-time SEO prerender + sitemap/robots — no SSR server. | | spark-ssr | Full-stack SSR on Bun — the template is the backend: inferred DB, REST CRUD, auth, live updates. Precompiled + response-cached: fast by default. | | spark-html-image | Build-time image optimization — webp/avif + responsive srcset, zero config. | | spark-html-font | Font loading optimizer — preload + size-adjusted fallbacks, no FOUT. | | spark-html-manifest | PWA manifest + icons + head tags (and optional service worker) from one config. | | spark-html-offline | Offline URL imports — a service worker that caches CDN components. | | spark-html-sri | Subresource Integrity — hash + verify assets and remote components. | | create-spark-html-app | Scaffold a spark-html app in one command. | | prettier-plugin-spark | Prettier for components — formats <script>/<style>, markup stays byte-for-byte. | | spark-html-language-server | LSP — diagnostics, go-to-definition, prop autocomplete, hover docs. |