Share State Across Devices
Problem
You have a stateful app: a shared editor, a live dashboard, a record under review, and want several people to see the same state on their own devices: one device owns the state, the others mirror it and send commands back. You need the pairing, the protocol, and the replication without hand-rolling 300 lines of session plumbing over @vielzeug/mesh.
Solution
Host the subject with hostTavern, wire the command table and snapshot access, and invite a guest with joinTavern: tavern owns the pairing, validation, and broadcasting.
ts
import { hostTavern, joinTavern } from '@vielzeug/tavern';
// 1. Host: the command table is the same object the host's own UI calls.
const host = hostTavern({
commands: {
rename: (args) => myStore.rename(docId, args[0] as string),
append: (args) => myStore.append(docId, args[0] as string),
},
subject: {
onChanged: (listener) => myStore.onUpdated(docId, listener),
onRemoved: (listener) => myStore.onRemoved(docId, listener),
snapshot: () => myStore.read(docId),
},
});
// 2. Pair: deliver the invitation code out-of-band (QR, copy/paste, navigator.share).
const invitationCode = await host.createInvitationCode();
// 3. Guest: consume the invitation code, produce the answer code to show back.
const { answerCode, guest, ready } = await joinTavern({
invitationCode,
mount: (snapshot) => {
const parsed = mySchema.parse(snapshot);
return parsed ? mountMirror(parsed) : null; // null ignores the snapshot
},
name: 'Alex',
onEnded: (subject) => unmountMirror(subject.id),
});
guest.tap((event) => {
if (event.type === 'rejected') showToast(event.message);
});
// 4. The host accepts the answer code; the channel opens.
await host.acceptAnswerCode(answerCode);
// 5. `ready` settles once the first snapshot arrives and mounts: navigate then.
const mirror = await ready;
navigateTo(mirror.id);
// 6. The guest's commands run through the host's own table; the effect
// comes back with the next snapshot, so no separate ack is needed.
guest.sendCommand('rename', ['Quarterly report']);
// 7. Cleanup: hosting ends for every guest; the guest fires onEnded once.
host.dispose();
guest.dispose();Pitfalls
- The snapshot arrives as parsed JSON: always validate in
mountbefore trusting it; returningnullsafely ignores it. - A command is fire-and-forget: success means "the host applied it and the next snapshot shows it". Watch for a
rejectedtap event to surface handler errors. - A tab that both hosts and guests needs an echo guard in
serializeNotice(one boolean set duringonNotice), or wire notices will re-broadcast back to the guests.
Related
- Usage Guide: hosting, joining, notice relaying, and best practices.
- API Reference: full signatures for every option and return type.
- Mesh: the P2P transport underneath.