_{View on npm      Source on GitHub}

nuxt-convex-module

Connects a Nuxt app to a Convex backend: live queries, mutations, actions, pagination, file storage and SSR, auto-imported and typed against your deployment.

_{The same Vue client runs without Nuxt; Better Auth, Clerk, Auth0 and Polar are opt-in.}

With an AI agent — paste this into Claude Code, Cursor, Codex or any agent that runs commands:

Install nuxt-convex-module, the Convex module for Nuxt, in this project:
run `npx skills add https://nuxt-convex-module.dev --skill nuxt-convex-module -y`,
then follow .agents/skills/nuxt-convex-module/references/install.md.

By hand

npx nuxi@latest module add nuxt-convex-module

Documentation · Installation · AI agents · Components · Upstream parity · Stability · Security

What you get

• ⚡ Live data — useQuery, useQueries, useMutation, useAction and cursor usePaginatedQuery, over one ConvexVueClient.
• 🖥️ SSR and preloading — useAsyncQuery, useAsyncPaginatedQuery, fetchQuery, preloadQuery for hydration-safe server rendering; fetchMutation / fetchAction on the Nitro side.
• 📁 File storage — useUpload, useUploadQueue, useStorageUrl and <ConvexImage>.
• 🔐 Auth state — provider-agnostic useConvexAuth / provideConvexAuth and the <Authenticated> / <Unauthenticated> / <AuthLoading> / <AuthRefreshing> components.
• 🧩 Opt-in integrations — install Better Auth, Clerk, Auth0 or Polar and they wire themselves up.
• 🛡️ Security — install nuxt-security and the CSP learns your deployment's origins.
• 🧰 DevTools — a Convex tab in Nuxt DevTools: connection, live subscriptions, server logs, auth state.
• 🤖 AI agents — an agent skill that installs the module and knows its API, a docs MCP server, and every page as Markdown.

All of it is auto-imported — composables and components in the app, fetch* helpers in Nitro — and also reachable through subpath exports. The same Vue client runs in a plain Vue app with no Nuxt involved.

Packages covered: convex (its /react, /nextjs, /react-clerk and /react-auth0 entry points), @convex-dev/better-auth and @convex-dev/polar — each with its pinned upstream version under Components.

How it's built

A Nuxt/Vue port of Convex's own React/Next client, hook for composable, not a reimagining: the public API keeps the names, arguments and return shapes Convex documents, so its docs and examples translate line for line. The port is kept diffable against upstream so new Convex releases can be tracked file-for-file — see Relationship to upstream and PARITY.md.

Composables follow VueUse conventions (MaybeRefOrGetter inputs, ComputedRef/ShallowRef returns). Authentication is provider-agnostic: the core ships the generic provideConvexAuth plumbing plus Vue adapters for Clerk and Auth0, while Better Auth and Polar are opt-in sub-modules — mirroring how @convex-dev/better-auth and @convex-dev/polar are separate packages upstream.

Documentation

nuxt-convex-module.dev is the single source of truth — installation, configuration, every guide, each supported package and the complete API reference live there and nowhere else, so this README does not repeat them. Its source is website/.

• Installation · AI agents · Configuration · Security · Troubleshooting
• Guide — queries, mutations and actions, pagination, file storage, server and SSR, auth state, connection state, DevTools, plain Vue
• Components — Better Auth, Clerk, Auth0, Polar
• API reference and Recipes

A taste

<script setup lang="ts">
import { api } from '#convex/api'

// SSR-rendered AND live-updating — Nuxt's { data, status, error } shape:
const { data: messages } = useAsyncQuery(api.messages.list, {})
const send = useMutation(api.messages.send)
</script>

<template>
  <ul><li v-for="m in messages" :key="m._id">{{ m.body }}</li></ul>
  <button @click="send({ body: 'hi' })">Send</button>
</template>

To start a new app, create it from templates/starter, a minimal Nuxt app with the module installed and one live Convex table:

pnpm create nuxt@latest my-app -t gh:qruto/nuxt-convex-module/templates/starter
# or, with npm (keep the `--`)
npm create nuxt@latest my-app -- -t gh:qruto/nuxt-convex-module/templates/starter

For something you can click around in, examples/playground runs every core feature from one page: live queries, mutations with optimistic updates, cursor pagination, file storage, actions, and server rendering with fetchQuery, one click each. Create it the same way with examples/playground in place of templates/starter. It's also what the Open in StackBlitz link on every pull request opens, with that commit's build already wired in, so a change can be tried in a real Nuxt app without setting one up. Both run against a Convex deployment of your own: dev starts Convex, which logs you in and pushes the app's functions.

Relationship to upstream

This package is intentionally kept diffable against the upstream React/Next sources so it can track new Convex / Better Auth / Polar releases. Each file mirrors its origin:

This package	Upstream
src/runtime/vue/**	convex/src/react/**
src/runtime/nuxt/**	convex/src/nextjs/**
src/runtime/clerk/**	convex/src/react-clerk/**
src/runtime/auth0/**	convex/src/react-auth0/**
src/runtime/better-auth/**	@convex-dev/better-auth/src/{react,nextjs}/**
src/runtime/polar/**	@convex-dev/polar/src/react/**

PARITY.md is the authoritative ledger: pinned upstream baselines, the file-by-file map, a compatibility matrix per upstream entry point, and every deliberate divergence with its reason and the test that pins it. It also carries the migration contract and the React→Vue translation rules the port is held to. The sync procedure itself is packaged as the upstream-parity skill.

STABILITY.md is the other contract: what a version number promises from 1.0.0 on — the covered surface, the experimental tier, and how an upstream release maps to a release here (an upstream breaking change is a major here, whatever upstream called it).

Contributing

Setup, project structure, the verification gate and the release flow are in CONTRIBUTING.md and RELEASE.md; how the port tracks upstream is in PARITY.md. Commits follow conventional commits.

Security

The security guide documents every security aspect in one place: the Convex-aware CSP, the hardened Better Auth proxy, auth tokens in SSR payloads, safe post-sign-in redirects, cross-domain one-time tokens, file-storage caveats, and a production checklist.

Found a vulnerability? Report it privately via GitHub Security Advisories — not in a public issue. See SECURITY.md.

License

MIT