convex-vue

library0.1.5jsnpmunverified

Convex-vue provides a seamless integration of Convex, the full-stack backend platform, with Vue.js applications. It is currently in version 0.1.5 and features real-time queries, support for Server-Side Rendering (SSR) and Static Site Generation (SSG) via Vue's Suspense, and optimistic updates for mutations. The library focuses on providing reactive composables like `useConvexQuery` and `useConvexMutation` to simplify data fetching and manipulation within Vue 3 components. While still in early development with minor version bumps, it shows an active release cadence addressing types, fixes, and enhancements, making it a viable option for Vue developers building applications with Convex. Key differentiators include its tight integration with Vue's reactivity system and built-in SSR capabilities.

web-framework database llm-agents ai-ml

npm install convex-vue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CONVEX-VUE

convex-vue

web-frameworkjavascriptv0.1.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

convexVue

✓ import { convexVue } from 'convex-vue'

✗ import convexVue from 'convex-vue'

The main plugin is a named export, not a default export. Ensure you destructure it correctly.

useConvexQuery

✓ import { useConvexQuery } from 'convex-vue'

✗ const { useConvexQuery } = require('convex-vue')

This library is primarily designed for ESM contexts. Avoid CommonJS `require` syntax.

useConvexMutation

✓ import { useConvexMutation } from 'convex-vue'

✗ import { useConvexMutation as mutate } from 'convex-vue'

The composable returns an object including `mutate`, `isPending`, and `error`. Directly aliasing the composable itself is incorrect usage.

useConvexClient

✓ import { useConvexClient } from 'convex-vue'

✗ import { ConvexClient } from 'convex-vue'

Access to the Convex client instance is provided via a composable (`useConvexClient`), not a direct class export from the integration package.

Initializes the Convex Vue plugin and demonstrates fetching real-time data using `useConvexQuery` to display a list of messages.

import { createApp, defineComponent, h } from 'vue'; import { convexVue, useConvexQuery } from 'convex-vue'; import { api } from './convex/_generated/api'; // Assume you have a convex project with a 'messages' module const App = defineComponent({ setup() { const { data: messages, isPending, error } = useConvexQuery(api.messages.list, {}); if (isPending.value) return h('div', 'Loading messages...'); if (error.value) return h('div', `Error: ${error.value.message}`); return h('div', [ h('h1', 'Convex Messages'), h('ul', messages.value?.map(msg => h('li', typeof msg === 'object' && 'text' in msg ? msg.text : String(msg)))) ]); } }); const app = createApp(App); app.use(convexVue, { url: process.env.VITE_CONVEX_URL ?? 'YOUR_CONVEX_DEPLOYMENT_URL_HERE' // Replace with your actual URL }); app.mount('#app');

Debug

Known issues

gotchaThe `data` return type of `useConvexQuery` was extended to include `undefined` in v0.1.1. This means queries can initially return `undefined` while loading, requiring explicit null/undefined checks in your components.

fix

Ensure your code handles `data.value` being `undefined` (e.g., `if (!data.value) { return 'Loading...'; }`).

affects: >=0.1.1

breakingThe `initClient` options interface was changed in v0.1.3 and then reverted in v0.1.4. If you upgraded to v0.1.3 and used the new interface, your code would have broken when upgrading to v0.1.4.

fix

Refer to the documentation for `v0.1.2` or `v0.1.4` for the correct `initClient` options. It's recommended to stay on `v0.1.4` or newer for stability.

affects: 0.1.3

gotchaConvex subscriptions (real-time updates) are not supported on the server side when using SSR. `useConvexQuery` will automatically trigger a standard, one-time query.

fix

Be aware that server-rendered content will not be real-time until the client-side takes over. For SSR, ensure you `await suspense()` to wait for initial query completion.

affects: >=0.0.1

breakingVersion 0.1.5 included a fix for duplicated types and better naming. While a 'fix', this could subtly change type inference or require adjustments if you were relying on previous type definitions.

fix

Review type errors after upgrading and adjust type annotations or usage patterns accordingly, especially for custom Convex function definitions.

affects: >=0.1.5

Errors

Common errors & fixes

TypeError: app.use is not a function

Attempting to use `convexVue` with something other than a Vue application instance, or `createApp` was not properly imported.

fix

Ensure your Vue app is created with `createApp(App)` and `app.use(convexVue, ...)` is called on the result.

Error: Cannot find module './convex/_generated/api'

The `api` object (generated by Convex) is not found at the specified path, or the Convex project hasn't been set up/code generated.

fix

Verify your Convex project is correctly set up, `npx convex dev` is running (or deployment is active), and the import path for `api` is correct relative to your project structure.

TypeError: Cannot read properties of undefined (reading 'myQuery') or 'Cannot read properties of undefined (reading 'call')'

The Convex `api` object or a specific function within it is undefined, often due to a typo in the module or function name, or a problem with your Convex deployment.

fix

Double-check the `api` path (e.g., `api.myModule.myQuery`) against your Convex function definitions and ensure your Convex deployment is healthy.

Query data is undefined on server-side render, but appears on client.

When using `useConvexQuery` with SSR, you must explicitly `await suspense()` to ensure data is fetched before rendering on the server.

fix

In your component setup, ensure you call `const { data, suspense } = useConvexQuery(...)` and then `await suspense()` before trying to access `data.value` for SSR.

Upgrade

Version history

0.1.5latest on npm

Audit

Dependencies

convexrequiredCore client for interacting with the Convex backend platform.

vuerequiredThe foundational Vue.js framework that convex-vue extends.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/chris-visser/convex-vue ↗

packagehttps://www.npmjs.com/package/convex-vue ↗

homepagehttps://www.convex.dev ↗