LocalHtmlDataTest/nostr

FolderSyncDB — Nostr + Folder Variant

Local-first browser key-value and document store with dual-sync: shared folder for local/offline use, plus Nostr relays for cross-device reach over the internet.

Why this variant?

The other variants sync browsers via a shared folder on disk. This only works when both browsers can access the same folder (same machine or network drive).

This variant adds Nostr relay sync as a second transport. Nostr relays are public WebSocket servers that relay messages between clients. Your browser connects directly to them — no server of your own, no accounts, no setup.

Laptop (file://)                       Phone (browser)
  ┌──────────┐                           ┌──────────┐
  │ IndexedDB │                           │ IndexedDB │
  └─────┬─────┘                           └─────┬─────┘
        │                                       │
   ┌────┴────┐                             ┌────┴────┐
   │  Sync   │                             │  Sync   │
   │ Engine  │                             │ Engine  │
   └──┬───┬──┘                             └──┬───┬──┘
      │   │                                   │   │
   Folder Nostr ──── wss://relay ──────── Nostr Folder

Use either or both:

• Folder only — local multi-browser sync, works offline
• Nostr only — cross-device sync, no folder needed
• Both — folder for local speed, Nostr for internet reach

How it works

On write:

1. Update IndexedDB (fast)
2. Write event file to folder (if folder connected)
3. Publish event to Nostr relay (if room joined)

On sync:

1. Scan folder for new events from other local browsers
2. Check Nostr relay cache for events from remote devices
3. Merge both, deduplicate by filename
4. Apply unseen events to IndexedDB
5. Bridge: folder events get published to Nostr, Nostr events get written to folder

Real-time push: When a Nostr subscription receives a new event, sync() is triggered immediately — no waiting for the polling interval.

Quick start

import { FolderSyncDB } from './nostr/src/index.ts';

const db = await FolderSyncDB.open({
  autoSyncIntervalMs: 5000,
  relays: [                        // optional, defaults to popular public relays
    'wss://relay.damus.io',
    'wss://nos.lol',
    'wss://relay.nostr.band',
  ],
});

// Local folder sync (same as other variants)
await db.selectFolder();

// Cross-device sync via Nostr
await db.joinRoom('my-shared-room-key');

// Use normally
await db.kv.set('theme', 'dark');
const theme = await db.kv.get('theme');

// Listen for events
db.on('nostr:connected', ({ roomKey }) => console.log('joined:', roomKey));
db.on('change', (e) => console.log('changed:', e));

API additions

On top of the standard FolderSyncDB API, this variant adds:

Method	Description
joinRoom(roomKey)	Join a Nostr sync room. All clients with the same key sync together.
leaveRoom()	Disconnect from the current room.
isConnected()	Whether a room is currently joined and relay is connected.
currentRoom	The current room key, or null.

OpenOptions additions

Option	Type	Default	Description
relays	string[]	3 popular public relays	Nostr relay WebSocket URLs
roomKey	string	none	Auto-join this room on open

Events additions

Event	Payload	When
nostr:connected	{ roomKey }	Joined a Nostr room
nostr:disconnected	--	Left a Nostr room

Room key

The room key is simply a shared string that identifies your sync group. It's used as a Nostr tag — all clients subscribed to the same tag receive each other's events.

• Anyone who knows the room key can join and sync
• Events are not encrypted (v1) — use random room keys for privacy through obscurity
• Each client generates its own Nostr keypair (stored in IndexedDB)

Works from file://

Nostr relays use WebSocket (wss://), which works from file:// origins in Chrome. Unlike WebRTC or fetch(), browsers don't block outgoing WebSocket connections from file:// pages.

Dependencies

• nostr-tools — lightweight Nostr protocol library (keypair generation, event signing, relay pool management). Pure JS, no WASM.

Local cache

Uses IndexedDB (same as the indexeddb/ variant). Zero-overhead, browser-managed persistence.