---
title: "Controller"
description: "Connect, reconfigure, or disconnect the Convex runtime explicitly when the deployment URL is not available at startup."
canonical_url: "https://nuxt-convex.onmax.me/vue-guide/controller"
---
# Controller

> Connect, reconfigure, or disconnect the Convex runtime explicitly when the deployment URL is not available at startup.

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

```ts [src/main.ts]
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

```vue [src/App.vue]
<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 realtime client in the browser. Queries that were waiting subscribe as soon as it exists.

## Reconfigure the runtime

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

```vue [src/components/TenantSelector.vue]
<script setup lang="ts">
import { useConvexController } from 'vue-convex/advanced'

const controller = useConvexController()

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

## Use the controller outside components

`useConvexController()` needs an injection context. Outside `setup()`, for example in a store or router guard, grab it through the app:

```ts [src/main.ts]
import { convexVue } from 'vue-convex'
import { useConvexController } from 'vue-convex/advanced'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App).use(convexVue, {})
export const controller = app.runWithContext(() => useConvexController())
app.mount('#app')
```

`createConvexVueController()` also exists, but it creates a separate runtime that no composable reads. Use it for scripts and tests, not to drive the app.

## Verify the result

The controller flow is working when:

- `controller.status.value` changes from `disconnected` to `connected`
- queries that were `pending` start receiving data after `connect()`
- `reconfigure()` switches to the new deployment without remounting the app

Before the runtime connects, queries stay `pending`, while mutations and actions reject with `Convex realtime client is not connected`.

## Next steps

- Read [Authentication](https://nuxt-convex.onmax.me/vue-guide/authentication) if the connection depends on the current user session
- Read [`useConvexController`](https://nuxt-convex.onmax.me/api-reference/use-convex-controller) for the exact controller contract


## Sitemap

See the full [sitemap](https://nuxt-convex.onmax.me/sitemap.md) for all pages.
