Start the client on demand
Keep the Convex WebSocket and the Better Auth client off public pages until a visitor needs them.
By default the module starts the browser runtime with the application. The browser runtime is the Convex client with its WebSocket and, when authentication is on, the Better Auth client. Every page then loads this code and opens a WebSocket, also for visitors who only read.
Set client.connect: 'on-demand' to start the browser runtime only when a page needs it. Public pages then load no Convex or Better Auth client code, send no session request, and open no WebSocket.
export default defineNuxtConfig({
modules: ['@lupinum/better-convex-nuxt'],
convex: {
client: { connect: 'on-demand' },
},
})When the runtime starts
With 'on-demand', the browser runtime starts in two cases:
- The application calls
useConvexActivation().activate(). - The route middleware reaches a page that needs to know the visitor, such as a
convexAuth: trueorconvexAuth: 'guest'page. The middleware starts the runtime, waits for the session, and then applies the redirect rules.
Server rendering does not change. useConvexQuery still fetches data on the server, and the page shows the server-rendered value.
Start it from your code
useConvexActivation() returns the mode, a reactive active flag, and activate():
<script setup lang="ts">
const { active, activate } = useConvexActivation()
const editing = ref(false)
async function startEditing() {
await activate()
editing.value = true
}
</script>
<template>
<button v-if="!editing" type="button" @click="startEditing">Edit</button>
<LazyEditor v-else />
</template>activate()loads the runtime code, creates the clients, and resolves when they exist. Calls at the same time share one start. If the code cannot load, the promise rejects and the next call tries again.activeistrueafter the runtime exists. It is alwaysfalseduring server rendering.- With the default
'eager'mode,activate()resolves at once.
You can also start the runtime from a client plugin, for example when a cookie shows that the visitor is an editor:
export default defineNuxtPlugin(async () => {
if (!useCookie('editor-hint').value) return
await useConvexActivation().activate()
})The cookie is only a hint for loading code. It does not give access to anything. Convex functions still check the user.
Rules for components
Mount a component that uses a Convex composable only after the runtime is active. Before that, useConvex() and useConvexAuth().client return stand-ins whose calls fail with code CLIENT_UNAVAILABLE, and a query composable in the browser has no client to subscribe with. Use v-if="active" or a lazy component that you show after activate().
useConvexAuth() is safe on every page. Before the runtime starts it reports the state from server rendering.
Cost
- The first activation downloads the runtime code and opens the WebSocket, so the first live update comes later than with
'eager'. connectis a build option. You cannot change it with a runtime environment variable.