Offline-first apps
Keep a copy of the data in the browser, so a field app reads and writes without a connection and syncs both ways when the network comes back.
Built from barrel-lite, a TypeScript client that speaks the same _sync wire as Barrel nodes, and barrel_server. barrel-lite is not on npm yet.
The problem
A field app has to keep working in a basement or a train and catch up later without losing edits. Request-per-action apps stop working offline, and hand-written sync queues lose one side of every concurrent edit.
How it fits together
-
In the browser
- Your web app TypeScript, reads and writes locally
- barrel-lite the local copy, stored in OPFS
- push and pull over HTTPS
-
barrel_server
- /db/:db/_sync the replication wire, with CORS
- Space sp_… the server copy
- replication
-
Other copies
- Other devices their own barrel-lite copy
- Erlang nodes embedded Barrel, same wire
The browser copy is a full replica: it stamps its writes with its own source id and keeps its own checkpoints, so the server needs no per-client state. Only one tab per origin syncs; other tabs go through it.
Build it
Six steps: build the client, open the server to the browser, then the code in your app.
-
Build barrel-lite
barrel-lite 0.1.0 is not on npm yet. Build it from the barrel repository and install it into your app from the local path.
cd barrel/clients/barrel-lite npm install && npm run build cd ../../../my-app npm install ../barrel/clients/barrel-lite -
Open the server to the browser
Allow your origin with CORS and expose
x-barrel-hlc, which carries the clock. Keep the global token on the server side.[{barrel_server, [ {cors, #{origins => [<<"https://app.example">>], expose => [<<"x-barrel-hlc">>]}}, {auth, #{tokens => [<<"global-token">>]}} ]}]. -
Give each device a token for one space
Your backend creates a space and grants a token:
readcovers pulling,writecovers pushing. The browser only ever holds that token.curl -X POST host:8080/spaces \ -H 'authorization: Bearer global-token' \ -H 'content-type: application/json' \ -d '{"label":"field-visits"}' curl -X POST host:8080/spaces/sp_…/grants \ -H 'authorization: Bearer global-token' \ -H 'content-type: application/json' \ -d '{"rights":["read","write"],"subject":"tablet-7"}' -
Open the local copy and write, online or not
Writes land in the local store at once and are pushed on the next sync. Storage is OPFS when the browser has it, memory otherwise.
import { Database } from "barrel-lite"; const db = await Database.open("visits", { remote: { url: "https://hub.example:8080", db: "sp_…", token: "bsp_…" }, multiTab: true, }); await db.put({ id: "v-311", site: "Lyon 2" }); const visit = await db.get("v-311"); -
Sync while the network is there
Live sync polls 500 ms after activity and backs off to 30 s when idle; a local write wakes it, and errors back off from 1 s to 60 s.
continuous: trueadds a server-sent event stream.const live = db.liveSync({ continuous: true }); db.onStatus((s) => setBadge(s.state)); // idle, syncing… db.onChange((c) => render(c.id, c.source)); // later live.stop(); -
Resolve conflicts on the device
If the device and another copy edited the same document apart, both versions are kept, on the device and on the server, and every copy shows the same winner.
resolvereplaces the winner and every conflict.const db = await Database.open("visits", { remote, onConflict: (e) => console.warn("conflict on", e.id), }); await db.sync(); const current = await db.get("v-311"); const others = await db.conflicts("v-311"); if (others.length > 0) { await db.resolve("v-311", merge(current, others)); await db.push(); }
What Barrel does
- Keeps the local copy in OPFS and answers reads and local BQL from it
- Pushes and pulls over
/db/:db/_sync, resuming from its checkpoints - Keeps concurrent versions as conflicts and picks the same winner as the server
- Elects one leader tab with Web Locks and relays the others over BroadcastChannel
- Syncs attachments, deduplicated by digest
What your application does
- Issues a capability token per device or user from your backend
- Shows sync status and offline state in the UI
- Merges conflicting versions in a way that fits your data
- Pulls a subset with a filter or a channel when a device should not hold everything
Limits
- Not on npm yet: build it from
clients/barrel-litein the repository. - The local store is a cache. Writes not yet flushed are lost on a crash, and the browser may evict the store (Safari does); the server copy is the source of truth.
- The
offlinestatus is never emitted: detect offline in your app, for example withnavigator.onLine. - Vector, keyword and hybrid search and
SUBSCRIBErun on the server only. There is no local full-text search; local vector search ranks the synced embeddings by brute force. - Bearer tokens only: no signed requests from the browser.