Skip to main content

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.

nuxt.config.ts
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:

  1. The application calls useConvexActivation().activate().
  2. The route middleware reaches a page that needs to know the visitor, such as a convexAuth: true or convexAuth: '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():

app/components/EditButton.vue
<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.
  • active is true after the runtime exists. It is always false during 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:

app/plugins/editor.client.ts
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'.
  • connect is a build option. You cannot change it with a runtime environment variable.