Skip to main content

Better Convex Nuxt

Add Convex to Nuxt with server-rendered queries, live updates, Better Auth, and server calls.

Better Convex Nuxt is a Nuxt module for Convex. You write Convex functions. The module lets Nuxt pages use them like any other Nuxt data source.

app/pages/index.vue
<script setup lang="ts">
import { api } from '#convex/api'

const { data: posts, status, error } = useConvexQuery(api.posts.list)
</script>

<template>
  <p v-if="status === 'pending'">Loading posts…</p>
  <p v-else-if="error">Could not load posts.</p>
  <ul v-else>
    <li v-for="post in posts" :key="post._id">{{ post.title }}</li>
  </ul>
</template>

This query runs on the server first, so the HTML already contains the posts. In the browser, the same posts ref then receives every change from Convex. You do not refetch or poll.

To try it, start the quick start.

What the module adds

  • Queries that render on the server and stay live in the browser
  • Reactive arguments, pagination, and loading and error state
  • Mutations and actions with pending, error, and data refs
  • Optimistic updates through the Convex local store
  • Better Auth sign-in, with the session available during server rendering
  • Convex calls from Nuxt server routes with serverConvex
  • File uploads, connection state, logging, and DevTools
  • An optional MCP package so ChatGPT and Claude can call your Convex functions

Why use it

A server-rendered live query must do several things in order. It runs on the server as the current user. It puts the result in the Nuxt payload. It hydrates without a loading flash. It starts a browser subscription as the same user. It restarts when arguments change. It clears data when the user signs out. It stops when the component unmounts.

These steps depend on each other. If you write them yourself, small timing errors can show one user's data to another user. The module does all of them inside useConvexQuery. How a request works explains each step.

What the module does not do

PartResponsible for
NuxtRendering, routing, server routes
ConvexDatabase, functions, live subscriptions
Better AuthSessions, cookies, sign-in methods
This moduleConnects the three above
Your applicationRoles, permissions, redirects, product rules

Check permissions inside Convex functions. A hidden button or a route redirect makes the UI nicer. It does not protect data.

What you still decide

  • Which Convex functions each user may call
  • Which queries render on the server and which start in the browser
  • Which Better Auth sign-in methods and plugins to use
  • How the UI shows errors, offline state, and pending writes

Read more