Controller

Use the controller when your app cannot connect at startup with a fixed Convex URL.

Common cases:

• multi-tenant apps that choose a deployment at runtime
• embedded apps that receive configuration from a host
• setups that wait until a user signs in before connecting

Install the base plugin without a URL

import { convexVue } from 'vue-convex'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)
app.use(convexVue, {})
app.mount('#app')

Without a URL, the runtime starts in the disconnected state.

Connect later

<script setup lang="ts">
import { useConvexController } from 'vue-convex/advanced'
import { onMounted } from 'vue'

const controller = useConvexController()

onMounted(() => {
  const url = window.localStorage.getItem('convex-url')
  if (url)
    controller.connect({ url })
})
</script>

connect() creates the HTTP client and, in the browser, the realtime client.

Reconfigure the runtime

Use reconfigure() when the deployment changes while the app is still mounted.

<script setup lang="ts">
import { useConvexController } from 'vue-convex/advanced'

const controller = useConvexController()

function switchTenant(url: string) {
  controller.reconfigure({ url })
}
</script>

Create a controller outside Vue injection

Use createConvexVueController() when the controller needs to live in a store or utility module.

import { createConvexVueController } from 'vue-convex/advanced'

export const controller = createConvexVueController()

Verify the result

The controller flow is working when:

• controller.status.value changes from disconnected to connected
• queries start succeeding after connect()
• reconfigure() switches to the new deployment without remounting the app

Queries, mutations, and actions throw if you call them before the runtime is connected.

Next steps

• Read Authentication if the connection depends on the current user session
• Read useConvexController for the exact controller contract