Skip to main content

Query Execution Options

Select SSR, authentication, and same-identity stale-data behavior for each query.

Query policy is deliberately per call. Transport and hydration behavior remain library invariants.

Server rendering

Queries run during SSR by default, reuse the Nuxt payload during hydration, and then stay live in the browser.

Set server: false only for genuinely browser-only data:

ts
const presence = useConvexQuery(api.presence.current, {}, { server: false })

There is no module-wide query policy. A caller can see the exceptional browser-only choice where it matters.

Optional await

Query refs exist immediately. Await the native Promise/state only when surrounding setup must wait for the initial SSR or browser settlement:

ts
const account = useConvexQuery(api.account.current, {}, { auth: 'required' })
const settled = await account

The Promise resolves for success, query error, skip, and server: false. Read settled.status.value and settled.error.value rather than wrapping setup in a rejection handler.

Auth modes

ts
useConvexQuery(api.account.current, {}, { auth: 'required' })
useConvexQuery(api.catalog.list, {}, { auth: 'optional' })
useConvexQuery(api.pages.home, {}, { auth: 'none' })
  • required waits for a usable identity and stays idle for an anonymous user.
  • optional waits for auth settlement, then runs authenticated or anonymously.
  • none ignores unrelated auth state and always uses anonymous transport, even for a signed-in user.

Use none only for identity-independent data, not as a performance switch for private queries.

Previous data

Add keepPreviousData: true when a same-identity argument transition should keep its last successful value visible. isStale marks that window. Identity replacement always retires previous data.

Cached pages

Do not publicly cache HTML containing authenticated SSR data. Per-query policy cannot correct a deployment cache that ignores identity. Use browser-only private data or identity-aware cache rules when a page cache is required.