Skip to main content

Query execution options

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

Set query options on each call. The module sets how the query reaches Convex and how it hydrates; you cannot change that part.

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 data that exists only in the browser:

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

There is no module-wide server default. The server: false choice stays visible at the call that needs it.

Optional await

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

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 signed-in user and stays idle for an anonymous user.
  • optional waits until the auth state is known, 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 data that is the same for every user. Do not use it to make a private query faster.

The default mode is optional. To change it for every query in the application, set convex.auth.defaultQueryAuth:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@lupinum/better-convex-nuxt'],
  convex: {
    auth: {
      origin: process.env.SITE_URL ?? 'http://localhost:3000',
      defaultQueryAuth: 'required',
    },
  },
})

The auth option of a call always wins over this default. Server rendering and the browser use the same value.

Previous data

Add keepPreviousData: true to keep the last result visible while new arguments load for the same user. isStale is true during that time. When the signed-in user changes, the previous data is always cleared.

Server limits

Each SSR query is one bounded Convex HTTP call. It fails with a transport error after convex.server.queryTimeoutMs (8 seconds by default) or when its response is larger than convex.server.maxResponseBytes (1 MiB by default). The error renders like any other query error and hydrates with the page. Change the limits in module configuration; do not raise them to hide an unbounded query. Paginate or narrow the query instead.

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.