{"id":13002,"library":"convex-vue","title":"Convex Vue Integration","description":"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.","status":"active","version":"0.1.5","language":"javascript","source_language":"en","source_url":"https://github.com/chris-visser/convex-vue","tags":["javascript","vue","convex"],"install":[{"cmd":"npm install convex-vue","lang":"bash","label":"npm"},{"cmd":"yarn add convex-vue","lang":"bash","label":"yarn"},{"cmd":"pnpm add convex-vue","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core client for interacting with the Convex backend platform.","package":"convex","optional":false},{"reason":"The foundational Vue.js framework that convex-vue extends.","package":"vue","optional":false}],"imports":[{"note":"The main plugin is a named export, not a default export. Ensure you destructure it correctly.","wrong":"import convexVue from 'convex-vue'","symbol":"convexVue","correct":"import { convexVue } from 'convex-vue'"},{"note":"This library is primarily designed for ESM contexts. Avoid CommonJS `require` syntax.","wrong":"const { useConvexQuery } = require('convex-vue')","symbol":"useConvexQuery","correct":"import { useConvexQuery } from 'convex-vue'"},{"note":"The composable returns an object including `mutate`, `isPending`, and `error`. Directly aliasing the composable itself is incorrect usage.","wrong":"import { useConvexMutation as mutate } from 'convex-vue'","symbol":"useConvexMutation","correct":"import { useConvexMutation } from 'convex-vue'"},{"note":"Access to the Convex client instance is provided via a composable (`useConvexClient`), not a direct class export from the integration package.","wrong":"import { ConvexClient } from 'convex-vue'","symbol":"useConvexClient","correct":"import { useConvexClient } from 'convex-vue'"}],"quickstart":{"code":"import { createApp, defineComponent, h } from 'vue';\nimport { convexVue, useConvexQuery } from 'convex-vue';\nimport { api } from './convex/_generated/api'; // Assume you have a convex project with a 'messages' module\n\nconst App = defineComponent({\n  setup() {\n    const { data: messages, isPending, error } = useConvexQuery(api.messages.list, {});\n\n    if (isPending.value) return h('div', 'Loading messages...');\n    if (error.value) return h('div', `Error: ${error.value.message}`);\n\n    return h('div', [\n      h('h1', 'Convex Messages'),\n      h('ul', messages.value?.map(msg => h('li', typeof msg === 'object' && 'text' in msg ? msg.text : String(msg))))\n    ]);\n  }\n});\n\nconst app = createApp(App);\n\napp.use(convexVue, {\n  url: process.env.VITE_CONVEX_URL ?? 'YOUR_CONVEX_DEPLOYMENT_URL_HERE' // Replace with your actual URL\n});\n\napp.mount('#app');","lang":"typescript","description":"Initializes the Convex Vue plugin and demonstrates fetching real-time data using `useConvexQuery` to display a list of messages."},"warnings":[{"fix":"Ensure your code handles `data.value` being `undefined` (e.g., `if (!data.value) { return 'Loading...'; }`).","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.1"},{"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.","message":"The `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.","severity":"breaking","affected_versions":"0.1.3"},{"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.","message":"Convex subscriptions (real-time updates) are not supported on the server side when using SSR. `useConvexQuery` will automatically trigger a standard, one-time query.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Review type errors after upgrading and adjust type annotations or usage patterns accordingly, especially for custom Convex function definitions.","message":"Version 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.","severity":"breaking","affected_versions":">=0.1.5"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your Vue app is created with `createApp(App)` and `app.use(convexVue, ...)` is called on the result.","cause":"Attempting to use `convexVue` with something other than a Vue application instance, or `createApp` was not properly imported.","error":"TypeError: app.use is not a function"},{"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.","cause":"The `api` object (generated by Convex) is not found at the specified path, or the Convex project hasn't been set up/code generated.","error":"Error: Cannot find module './convex/_generated/api'"},{"fix":"Double-check the `api` path (e.g., `api.myModule.myQuery`) against your Convex function definitions and ensure your Convex deployment is healthy.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'myQuery') or 'Cannot read properties of undefined (reading 'call')'"},{"fix":"In your component setup, ensure you call `const { data, suspense } = useConvexQuery(...)` and then `await suspense()` before trying to access `data.value` for SSR.","cause":"When using `useConvexQuery` with SSR, you must explicitly `await suspense()` to ensure data is fetched before rendering on the server.","error":"Query data is undefined on server-side render, but appears on client."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}