Vue Query live adapter

A published npm adapter bridging webedge-db live queries into TanStack Vue Query.

TypeScriptVue Querywebedge-db

Dev-story01

Challenge

Reactive backends often ship a React Query adapter, but Vue teams had to wire live queries into TanStack Vue Query by hand and invalidate the cache themselves.

What we did

A published TypeScript package that subscribes to the reactive backend over the WebSocket and writes each live result straight into the TanStack Vue Query cache.

Result

Vue 3 components use normal `useQuery` calls and the data stays live automatically — no refetch, no manual invalidation. Published on npm as `convex-vue-query`.

Dev-story article

Vue Query live adapter: how the project was built

TanStack Query is built on a pull model: you fetch, you cache, and you invalidate by hand when something changes. Our reactive backend works the opposite way, pushing new query results over a WebSocket the moment the underlying data moves. A React bridge for this pattern already existed, but Vue teams had nothing, so every screen ended up with hand-rolled subscription glue and stale-cache bugs.

Sections

Modules

Stack

TypeScript + Vue Query

Why the project exists

Reactive backends often ship a React Query adapter, but Vue teams had to wire live queries into TanStack Vue Query by hand and invalidate the cache themselves.

What was built

A published TypeScript package that subscribes to the reactive backend over the WebSocket and writes each live result straight into the TanStack Vue Query cache.

convex-vue-query is a small adapter that wires the reactive backend's live subscriptions into TanStack Vue Query as the transport layer. A ConvexQueryClient supplies a custom queryKeyHashFn and queryFn, connects to the shared QueryClient, and streams subscription updates directly into the cache. Components just call useQuery(convexQuery(...)) and the data stays live on its own.

Main modules and user path

M01

convexQuery() plus a ConvexQueryClient that owns the queryKeyHashFn/queryFn pair and pushes WebSocket results into the TanStack cache instead of polling

M02

Subscription lifecycle tied to observers: a live query is only open while a Vue Query observer is mounted, and inactive queries are unsubscribed so sockets don't leak

M03

convexPaginatedQuery(), which injects paginationOpts and exposes live { results, status, canLoadMore, loadMore } for cursor-based lists

M04

useConvexMutation() with native optimistic updates through the backend's local store, plus convexAction() for non-live action-as-query calls

M05

SSR path via the HTTP client with consistent-query semantics by default, and an explicit disconnect() for HMR dispose and app teardown

Architecture and technology decisions

Built with TypeScript, Vue Query, webedge-db.

Written in TypeScript against Vue 3 and TanStack Vue Query, it mirrors the existing React adapter's contract and sets staleTime to Infinity since pushed data is never stale, keeping the whole thing a thin transport layer rather than a second cache.

Result and lessons

Vue 3 components use normal `useQuery` calls and the data stays live automatically — no refetch, no manual invalidation. Published on npm as `convex-vue-query`.

A published npm package that gives Vue apps realtime queries, pagination, and optimistic mutations with no manual invalidation, closing the gap between the reactive backend and the Vue ecosystem.