Zero Code Changes
Your existing Convex queries and mutations run unmodified in the browser. The returned ConvexClient works with ConvexProvider, convex-svelte, and every Convex framework integration.
Introduction
@robelest/convex-embedded is an embedded Convex runtime that runs entirely in the browser. It executes your existing Convex query and mutation functions locally against an in-browser SQLite database, giving your app instant reads, instant writes, and full offline support — all without changing a single line of your Convex function code.
When remote sync is enabled, the embedded runtime becomes a local-first engine: mutations write locally first and replay to the remote Convex deployment in the background. A Yjs CRDT resolve pass automatically merges any state that diverged while offline.
Key Features
Offline-First
Reads and writes work instantly with no network. Mutations queue locally and replay to the remote deployment when connectivity returns. The CRDT resolve engine merges divergent state automatically.
CRDT Fields
Declarative field types -- register, prose, counter, set, and omit -- map to Yjs data structures for fine-grained conflict resolution. Rich text fields merge at the character level.
Cross-Tab Sync
Tabs sharing the same IndexedDB database name receive instant updates via BroadcastChannel. Write in one tab, see the result in all others -- no server round-trip required.
Persistent Storage
Documents persist to IndexedDB via wa-sqlite running in a Dedicated Worker. Data survives page refreshes and browser restarts.
Framework Agnostic
Works with React, Svelte, Vue, or any framework that integrates with the standard Convex ConvexClient. No framework-specific wrapper needed.
When to Use It
convex-embedded is a good fit when you need:
- Local-first applications — users expect instant interactions with no loading spinners, even on slow or unreliable networks.
- Offline support — the app must remain fully functional without a network connection (field workers, mobile apps, airplane mode).
- Collaborative editing — multiple users (or multiple tabs) edit the same data concurrently and expect automatic conflict resolution.
- Reduced latency — reads and writes resolve in microseconds against the local database instead of a network round-trip.
It is not the right choice when:
- You need server-authoritative validation that cannot be replicated client-side (e.g., payment processing, access control that must be enforced server-side).
- Your dataset is too large to fit in the browser’s IndexedDB quota.
- You do not use a Vite-based bundler (the module discovery relies on
import.meta.glob).
Next Steps
Head to the Installation page to add @robelest/convex-embedded to your project, or jump straight to the Quick Start for a step-by-step walkthrough.