Hi, I'm building an email client and would like to be able to open it without an established internet connection too. I'm using tanstack start and have heard in podcasts that there could be a cool interplay with tanstack db for this stuff. What's the current status and best approach for syncing and caching convex data locally?
#Local caching/fallback for offline access
solemn scarab
rancid windBOT
Hi @solemn scarab. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
Great question! Here's an honest summary of the current state of local-first/offline support in Convex:
Current Status
Convex does not yet have a built-in, first-class local-first/offline solution. As one Convex support staff member put it directly:
"There isn't really a local first approach with Convex. The team has big thoughts on how to handle local sync correctly, though, and it's been an active target for some time." [Local first apps]
What's Being Built
Convex is actively working on an object sync engine that would provide:
- A local store (likely IndexedDB initially, with SQLite planned for cross-platform support)
- A sync protocol for initial sync, incremental sync, and offline mutation buffering
- Local queries via
ctx.localDband optimistic local mutations
The API being designed looks like this:
// Local query
const isFriend = useLocalQuery(async (ctx) => {
const friendship = await ctx.localDb.query("friendships")
.withIndex("by_from_to", q => q.eq("from", user).eq("to", friend))
.unique();
return friendship !== null;
});
// Local mutation with server fallback
const addFriend = localMutation({
server: api.friends.addFriend,
local: async (ctx, args) => {
await ctx.localDb.insert("friendships", { ... });
},
});
However, this is not yet released.
Best Approach Today
If you need offline support right now, the most viable documented approach is to use Automerge (a CRDT library) alongside Convex:
- Automerge stores document state and history in IndexedDB locally, so data persists across browser restarts and works offline.
- Changes are synced to Convex when connectivity is restored, using Convex mutations (which queue up offline and deliver exactly once on reconnect).
- New clients can sync from a snapshot stored in Convex rather than replaying all changes.
This is a more complex, lower-level approach and requires reasoning through distributed state problems carefully.
Regarding TanStack Start
The knowledge sources don't contain specific information about a TanStack DB + Convex offline interplay. The TanStack Start docs cover live-updating queries and SSR preloading, but not offline/local caching. [TanStack Start]