Local-First Architecture

How Persist keeps your data on the device first and syncs when connectivity is available.

What local-first means

Local-first software writes data to a local database before anything else. There is no mandatory server round-trip for reads or writes. The network is used for replication, not as a primary data path. This gives you instant reads, zero-latency writes, and full offline capability.

Persist implements local-first by defaulting every store to a local SQLite adapter. When you call store.records.put(), the write goes to disk immediately. A background sync queue picks up new writes and pushes them to configured remotes.

Offline-first by default

Every Persist store works without a network connection. The sync engine maintains a write-ahead queue that accumulates operations while offline. When connectivity returns, the queue drains automatically in order.

const store = await createStore("notes", {
  adapter: "sqlite",
  path: "./notes.db",
});

// These work offline — no network needed
await store.records.put("note:1", { text: "Draft while offline" });
const note = await store.records.get("note:1");

There is no special “offline mode” to enable. Offline operation is the baseline behavior.

Sync-on-connect

When a remote is configured, Persist watches for connectivity changes. On reconnect, it performs a three-step sync cycle:

1. Push — local writes queued since the last sync are sent to the remote.
2. Pull — remote writes from other devices are fetched.
3. Merge — conflicts are resolved using the configured strategy (last-write-wins, custom merge function, or manual resolution).

The sync planner batches operations and deduplicates redundant writes to minimize bandwidth.

Why local-first matters

Traditional cloud-first architectures tie application responsiveness to network latency. A slow API means a slow UI. Local-first inverts this: the UI is always fast because reads and writes hit local storage. The network is an optimization for durability and multi-device access, not a prerequisite for function.

This architecture also gives users real ownership of their data. Records exist on the device regardless of server availability, making data portability and export straightforward.