Offline & sync health

Your app already works offline. This page is about showing the user what's going on, and tuning what gets cached.

There’s no offline mode to switch on. Reads are served from the local store, writes queue locally and drain when the network returns. What you do have to build is the UI that tells the user which state they’re in.

import { useSyncStatus } from '@spooky-sync/client-solid';
import { Show } from 'solid-js';

function ConnectionBanner() {
  const sync = useSyncStatus();

  return (
    <Show when={sync.isOffline()}>
      <div class="banner">Can't reach the server, changes are saved locally.</div>
    </Show>
  );
}

Sync health

A single dropped request never trips the banner. useSyncStatus reports degraded only after a run of consecutive failed sync rounds (three by default) and flips back on the first successful round.

Tune the threshold in your client config:

const dbConfig: SyncedDbConfig<typeof schema> = {
  // …
  syncHealth: { degradeAfterConsecutiveFailures: 5 },
};

Pass syncHealth: false to never report degraded at all.

Traffic indicator

useSyncActivity answers a different question again: is data moving right now? It is the hook behind an app-chrome mark that switches to “downloading” or “uploading”.

import { useSyncActivity, useSyncStatus } from '@spooky-sync/client-solid2';
import { Show } from 'solid-js';

function SyncMark() {
  const { isDownloading, isUploading, pendingMutations } = useSyncActivity({ downloadDelayMs: 200 });
  const { isOffline } = useSyncStatus();

  return (
    <span class="mark">
      <Show when={isUploading()} fallback={<Show when={isDownloading()}>⬇</Show>}>⬆</Show>
      <Show when={isOffline() && pendingMutations() > 0}>
        <span class="badge">{pendingMutations()} unsaved</span>
      </Show>
    </span>
  );
}

While isOffline() is true, pendingMutations() is the number of changes that are saved locally and not yet on the server. Show it: a count is more reassuring than a sentence.

Connection vs. health

These answer different questions and it’s worth keeping them apart:

• connection() is about the socket. It flips the moment the WebSocket drops.
• status() is about whether sync rounds are succeeding. It only degrades after a sustained run of failures.

A short reconnect is usually reconnecting and still healthy — writes queue locally and push once the socket is back, so there’s nothing to alarm the user about. Use isReconnecting() for a quiet spinner and isOffline() for the actual “we can’t reach the server” banner.

Reconnect

The client keeps the connection alive for as long as the page lives. Three things cooperate:

1. The SurrealDB SDK retries after a socket close, on exponential backoff. Sp00ky configures this to retry indefinitely rather than the SDK’s default of five attempts (which gives up after roughly a minute of downtime and never tries again).
2. A supervisor re-opens the connection from scratch if the SDK stops trying at all.
3. A heartbeat probes the server on an interval. This is what catches a half-open socket: the peer is gone (laptop slept, wifi switched, NAT timed out) but no close event ever arrives, so nothing else would notice. If a probe goes unanswered the socket is torn down and rebuilt.

Coming back online or un-hiding the tab also triggers an immediate probe instead of waiting out a backoff.

After any reconnect, active queries re-register and live subscriptions are re-issued — a live subscription is scoped to its WebSocket session, so it does not survive the drop.

The defaults need no configuration, but they’re tunable:

const dbConfig: SyncedDbConfig<typeof schema> = {
  database: {
    // …
    reconnect: {
      attempts: -1,                 // -1 = retry forever (the default)
      retryDelayMax: 15_000,        // cap on the backoff between attempts
      heartbeatIntervalMs: 20_000,  // liveness probe cadence; 0 disables
      heartbeatTimeoutMs: 10_000,   // unanswered for this long = socket is dead
    },
    queryTimeoutMs: 60_000,         // deadline on every remote query; 0 disables
  },
  pushTimeoutMs: 30_000,            // deadline on a single outgoing mutation
};

Pending writes

Mutations made while offline sit in a queue. pendingMutationCount is how many are waiting, and subscribeToPendingMutations fires whenever it changes.

const [pending, setPending] = createSignal(db.pendingMutationCount);
onCleanup(db.subscribeToPendingMutations(setPending));

<Show when={pending() > 0}>
  {pending()} change{pending() === 1 ? '' : 's'} not yet synced
</Show>

Useful for a “3 changes not yet saved” indicator, and for warning before the user closes the tab with unsynced work.

The Dart client also reports which records are still waiting. unsyncedRecordIds is the set of record ids with a write the server has not acknowledged yet, and subscribeToUnsyncedRecords fires whenever that set changes, even when the count stays the same because one write was acknowledged as another was queued. Use it for a per-row indicator, like one tick while a message is only on the device and two once it is stored.

// Dart: one tick while the row is only on this device, two once it is stored.
Set<String> unsynced = client.unsyncedRecordIds;
final stop = client.subscribeToUnsyncedRecords((ids) {
  setState(() => unsynced = ids);
});

final stored = !unsynced.contains(conversation.id);

// In dispose():
stop();

Where data lives locally

Set database.store in your client config:

Reads hit this store first, so a returning user sees their data on the first frame, before any network round trip completes.

Preloading

db.preload() registers a query without rendering it. Run it on a route you’re about to navigate to and the next screen paints instantly.

// warm the thread list before the user navigates to it
await db.preload(db.query('thread').orderBy('created_at', 'desc').limit(20).build());

// abortable when the route changes before the data lands
const ctrl = new AbortController();
void db.preload(db.query('thread').build(), { signal: ctrl.signal });

A preloaded query stays registered (and live) until a ttl after nothing has mounted it; a view that mounts the same query simply attaches to it.

Telling clients a new version shipped

Deployed frontends write an announcement row that running clients can see. useAppRelease surfaces it so you can offer a reload, or force one when you’ve shipped a fix for a broken build.

import { useAppRelease } from '@spooky-sync/client-solid';
import { Show, createEffect } from 'solid-js';

function UpdatePrompt() {
  const release = useAppRelease({
    app: 'web',
    currentVersion: __APP_VERSION__,   // baked in at build time
  });

  // a mandatory release reloads without asking
  createEffect(() => {
    if (release.updateAvailable() && release.mandatory()) release.reload();
  });

  return (
    <Show when={release.updateAvailable()}>
      <button onClick={() => release.reload()}>
        Update to {release.latestVersion()}
      </button>
    </Show>
  );
}

Announce a release without a full deploy with spky release.

Next