Skip to main content

Query Execution Options

Select SSR, subscription, timeout, and authentication behavior for each query.

Choose query behavior from requirements, not habit.

Execution matrix

serversubscribeBehavior
truetrueSSR HTTP result, hydration reuse, then live subscription
falsetrueBrowser-only live query
truefalseSSR snapshot without live updates
falsefalseBrowser-only one-shot query

Both options default to true.

Configure one query

ts
const report = await useConvexQuery(
  api.reports.snapshot,
  { reportId },
  {
    subscribe: false,
    auth: 'required',
  },
)

Configure application defaults

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['better-convex-nuxt'],
  convex: {
    defaults: {
      server: true,
      subscribe: true,
      waitTimeoutMs: 10_000,
    },
  },
})

Per-query options override server and subscribe. Authentication mode remains explicit per query and always defaults to optional.

First live-result timeout

An awaited subscribe-mode query waits for its first browser WebSocket result. waitTimeoutMs defaults to 10 seconds.

  • Use a finite timeout so navigation can recover from a failed connection.
  • Set 0 only when an indefinite wait is intentional.
  • The timeout is not the lifetime of the subscription. It only bounds the awaited first result.

Auth modes

ts
await useConvexQuery(api.account.current, {}, { auth: 'required' })
await useConvexQuery(api.catalog.list, {}, { auth: 'optional' })
await useConvexQuery(api.pages.home, {}, { auth: 'none' })

none uses anonymous transport even for a signed-in user. Use it for truly identity-independent data, not as a performance switch for private queries.

Cached pages

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

Report an issue