@namesmt/convex-vue

Convex Vue

Convex integration for Vue!

convex-vue

• convex-vue
  • Overview
  • Features
  • Usage
    • Install package
    • Import and use
    • Composables
      • useConvexClient
      • useConvexQuery
      • useConvexMutation
      • Suspense and SSR Support
  • License

Overview

convex-vue is a Vue.js integration library for Convex - the backend application platform with a built-in database.

Features

• 👌 Supports Convex realtime queries
• 🔄️ SSR and SSG support via suspense

Usage

Install package

# npm
npm install convex-vue

# bun
bun add convex-vue

# pnpm (recommended)
pnpm install convex-vue

Import and use

Convex Vue is a Vue 3 plugin. Simply add it to your Vue app and use the provided composables.

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

const app = createApp(App)

app.use(convexVue, {
  url: 'your-convex-deployment-url'
})

app.mount('#app')

Composables

useConvexClient

The useConvexClient composable provides access to the Convex client instance. You can use it to call Convex functions directly or implement custom logic.

import { useConvexClient } from 'convex-vue'

// In your component
const client = useConvexClient()

useConvexQuery

The useConvexQuery composable is used to fetch data from Convex. It automatically handles subscriptions and reactivity, so your components will update in real time when the data changes.
On the server, it will trigger a standard query (without subscription).

import { useConvexQuery } from 'convex-vue'
import { api } from '../convex/_generated/api'

// In your component or composable
const { data, isLoading, error } = useConvexQuery(api.myModule.myQuery, { param: 'value' })

useConvexMutation

The useConvexMutation composable is used to call Convex mutations. It provides a function that you can call to trigger the mutation, and it automatically handles loading and error states.

import { useConvexMutation } from 'convex-vue'
import { api } from '../convex/_generated/api'
// In your component or composable
const { mutate, isLoading, error } = useConvexMutation(api.myModule.myMutation)

async function handleClick() {
  // mutate returns a promise with an object that contains a result or error property
  const { result, error: mutationError } = mutate({ param: 'value' })
}

Suspense and SSR Support

By default when using useConvexQuery, the data property will be undefined until the query is complete.
By using the suspense function, you can await the result of the query. This is useful for server-side rendering (SSR)
and Static Site Generation (SSG) where you want to wait for the query to complete before rendering the component.

Convex subscriptions on the server are not supported. useConvexQuery therefore triggers a standard query.
If you await the suspense function, it will resolve when the query is complete or reject with an error.

// In your component or composable
const { data, suspense } = useConvexQuery(api.myModule.myQuery, { param: 'value' })

const result = await suspense()
// Now you can use the data or result
console.log(data)
console.log(result)

Either use the result of the suspense function like below, or simply use the data property.
The suspense function will only return the result once on server and client (like a normal promise).
The data property will be reactive and update when the query result changes on the client.
Recommended to use the data property for SSR support and realtime clientside updates.

License

Changelog

v0.1.1

compare changes

🩹 Fixes

• Add undefined to data return type of useConvexQuery (77ffae5)
• Reactive query args & scope cleanup (963e54f)

📖 Documentation

• Update readme for optimistic updates (97c1985)

❤️ Contributors

• Louis Haftmann (@LouisHaftmann)
• Chris Visser (@chris-visser)