Performance
Remove unnecessary query stages, reduce payloads, and measure the Nuxt-to-Convex lifecycle.
Optimize the lifecycle you actually use. Do not add another cache before identifying the expensive stage.
Recommended order
- Measure SSR, navigation, payload size, and subscription activity.
- Move browser-specific data out of SSR when it does not improve initial HTML.
- Return less data and paginate growing collections.
- Avoid unnecessary auth work on public paths.
- Tune the deployment only after you measure the result.
Remove unnecessary SSR
Use server: false for browser-specific data that does not improve the initial HTML.
useConvexQuery(api.presence.current, {}, { server: false })The cost is a browser loading state and no server-rendered value.
Use imperative calls for snapshots
Composable query state is live by design. For a one-shot operator action or snapshot, call through the restricted client handle instead of mounting reactive state:
const convex = useConvex()
async function exportReport() {
const report = await convex.query(api.reports.monthly, args)
downloadCsv(report)
}Create the handle during setup and call it from a browser event handler. During server rendering, its calls reject with code CLIENT_UNAVAILABLE.
Keep public data independent of auth
auth: 'none' does not wait for the auth state and always uses anonymous transport. Use it only for functions whose result and authorization are truly identity-independent.
Bound result size
Return fields the page uses. Use indexes and take() for bounded lists. Use pagination for growing collections. Large SSR results increase Convex work, HTML/payload size, parsing, and hydration cost.
SSR queries and serverConvex reject a response larger than convex.server.maxResponseBytes (1 MiB by default) and stop a query after convex.server.queryTimeoutMs (8 seconds by default). Treat these limits as a signal to narrow the query before you raise them. See server limits.
Understand duplicate dashboard calls
The default SSR-to-live lifecycle creates one server HTTP query and one browser subscription. This is not a duplicate subscription bug. Disable a stage only when its product benefit is unnecessary.
Count auth calls
With auth enabled, a signed-in page load also runs Better Auth in Convex. The server render reads the session and exchanges it for a Convex token. The browser then reads the session and fetches its own token. Each of these requests runs a few component functions in Convex: session and user lookups, and a rate-limit write for the token request. Expect roughly 15 to 25 auth function calls per signed-in page load, next to the 2 calls of each query. Anonymous page loads run none.
To lower the count, render pages that need no user without SSR auth work (auth: 'none' queries on public pages), and keep the number of full page loads low; client navigation reuses the session and the token.
Avoid a mirrored store
Copying Convex entities into Pinia adds update and identity-clearing work. Use normal queries and keep stores for UI-only state.
Measure production behavior
Development includes HMR, DevTools, source maps, and extra diagnostics. Use production builds and representative deployment regions before drawing latency conclusions.