Composables

These APIs are auto-imported in Nuxt application code. Import generated function references from #convex/api.

Query APIs

useConvexQuery

const state = useConvexQuery(query, args, options?)
const settled = await state // optional initial-settlement barrier

Exactly empty query validators may omit args. A validator with any declared key requires that position, even when every key is optional. Use 'skip' as the argument value to make the state idle.

Nuxt options: auth, keepPreviousData, server. Plain Vue omits server.

Immediate readonly state: data, status, pending, error, isStale, refresh.

data and error use undefined for absence. A query result of null is successful data. The Nuxt return is also a native Promise; its awaited result is a separate non-Promise view of the same refs. Initial success, error, skip, and server: false resolve. Query guide.

useConvexPaginatedQuery

const state = useConvexPaginatedQuery(query, args, {
  initialNumItems,
  auth?,
  keepPreviousData?,
  server?,
})
const settled = await state // optional

initialNumItems is required. Immediate readonly state: data, status, isLoading, canLoadMore, error, isStale, loadMore, refresh.

Status is idle, pending, success, or error. data is the flattened readonly item array or undefined. The Nuxt return follows the same native Promise/state settlement contract as a regular query. Pagination guide.

Write APIs

useConvexMutation

const mutate = useConvexMutation(mutation, { optimisticUpdate? })

Returns one direct callable with readonly data, status, pending, and error. optimisticUpdate(store, args) is synchronous and uses Convex's OptimisticLocalStore methods getQuery, getAllQueries, and setQuery directly. Mutation guide.

useConvexAction

const run = useConvexAction(action)

Returns one direct callable with readonly data, status, pending, and error. Action guide.

Authentication API

useConvexAuth

const { status, isPending, user, error, client, ready } = useConvexAuth()

Returns the canonical authentication state and one configured, integrated Better Auth client:

• status: loading, anonymous, authenticated, or error for the currently usable identity;
• isPending: Better Auth session or operation work, independent from status;
• readonly user and error refs;
• client: the inferred Better Auth client in the browser, or null during SSR/early setup;
• ready(): waits for initial Convex identity settlement.

Render auth states explicitly so application layout and accessibility stay product-owned:

<script setup lang="ts">
const { status, error } = useConvexAuth()
</script>

<template>
  <AccountSkeleton v-if="status === 'loading'" />
  <AccountMenu v-else-if="status === 'authenticated'" />
  <SignInCard v-else-if="status === 'anonymous'" />
  <ErrorCard v-else :message="error?.message ?? 'Authentication failed'" />
</template>

Synchronous Better Auth methods such as client.useSession() remain synchronous. Every Promise-returning client operation re-reads the canonical provider session and settles only after Convex accepts that exact session generation. $fetch, $store, hydrateSession, and the module-owned Convex token action are not exposed.

Auth state guide.

Query product profiles directly with useConvexQuery(..., { auth: 'required' }); session identity remains owned by useConvexAuth().

Client and configuration

useConvex

useConvex()

Client-only. Returns one stable handle containing exactly query, mutation, action, and onUpdate. It throws when the client runtime or Convex URL is unavailable.

useConvexAttachment

useConvexAttachment()

Client-only. Returns the frozen @lupinum/better-convex-vue/embedded attachment owned by the current Nuxt app for an explicitly embedded Vue application. It contains no credentials or Better Auth controls.

useConvexConfig

const { url, siteUrl } = useConvexConfig()

Returns exactly the readonly resolved Convex deployment URL and HTTP Actions site URL. It exposes no auth, query policy, upload policy, logging, or server-secret fields.

useConvexConnectionState

useConvexConnectionState()

Returns the maintained connection-state view. Use operation and query state for product-level availability.

File API

useConvexFileUpload

useConvexFileUpload(generateUploadUrlMutation, options?)

Options: maxSize, allowedTypes.

Returns: upload, branded storage-ID data, status, pending, readonly byte-level progress, error, cancel. Generated mutation arguments keep their Convex arity: required arguments are required by upload(file, args).

Resolve URLs with an ordinary useConvexQuery call. Products that accept several files own their item state, worker count, retry policy, and persistence around this one-file primitive. File guide.