Composables
Reference for every auto-imported Better Convex Nuxt composable and optimistic helper.
All APIs on this page are auto-imported in Nuxt application code. Import api from #convex/api.
Query APIs
useConvexQuery
await useConvexQuery(query, args, options?)Options: server, subscribe, initialData, transform, keepPreviousData, auth.
Returns: data, error, refresh, clear, pending, status, isStale.
Use 'skip' as the arguments value to disable execution. Query guide.
defineSharedConvexQuery
defineSharedConvexQuery({ key, query, args, options? })Returns a zero-argument composable that creates one shared query state per Nuxt app. The options and return state match useConvexQuery. Sharing guide.
useConvexPaginatedQuery
await useConvexPaginatedQuery(query, args, options?)Options: initialNumItems, server, subscribe, initialData, transform, keepPreviousData, auth.
Returns: results, status, isLoading, isStale, hasNextPage, loadMore, error, refresh, reset.
Status is idle, loading-first-page, ready, loading-more, exhausted, or error. Pagination guide.
Write APIs
useConvexMutation
useConvexMutation(mutation, options?)Options: optimisticUpdate, onSuccess, onError.
Returns a callable with .safe(), data, status, pending, error, and reset(). Mutation guide.
useConvexAction
useConvexAction(action, options?)Options: onSuccess, onError.
Returns a callable with .safe(), data, status, pending, error, and reset(). Action guide.
Regular optimistic helpers
These functions run inside a mutation's optimisticUpdate(store, args) callback.
| Helper | Required fields |
|---|---|
updateQuery | query, exact args, store, updater |
setQueryData | query, exact args, store, value |
updateAllQueries | query, optional argsToMatch, store, updater |
deleteFromQuery | array query, exact args, store, shouldDelete |
Paginated optimistic helpers
| Helper | Required fields |
|---|---|
insertAtTop | query, optional argsToMatch, store, item |
insertAtPosition | previous fields plus sortOrder, sortKeyFromItem |
insertAtBottomIfLoaded | query, optional argsToMatch, store, item |
updateInPaginatedQuery | query, optional argsToMatch, store, updateValue |
deleteFromPaginatedQuery | query, optional argsToMatch, store, shouldDelete |
See optimistic updates.
Authentication APIs
useConvexAuth
useConvexAuth()Returns: status, isPending, isAuthenticated, user, token, error, signIn, signUp, signOut, refresh, ready, client.
Status is disabled, loading, anonymous, authenticated, or error. Auth state guide.
useConvexUser
useConvexUser(query, args, options?)Options: source, transform, seedFromSession, subscribe.
Returns: state, data, pending, status, isStale, error, source, refresh, clear.
The source is none, session, better-auth, or projection.
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.
useConvexConfig
useConvexConfig()Returns the normalized read-only public runtime configuration for the current Nuxt app. It does not expose server secrets.
useConvexConnectionState
useConvexConnectionState()Returns: state, isConnected, isReconnecting, pendingMutations, pendingActions, shouldShowOfflineUi.
File APIs
useConvexFileUpload
useConvexFileUpload(generateUploadUrlMutation, options?)Options: onSuccess, onError, onProgress, maxSize, allowedTypes.
Returns: upload, data, status, pending, progress, error, cancel.
useConvexUploadQueue
useConvexUploadQueue(generateUploadUrlMutation, options?)Options: maxConcurrent, continueOnError, onItemSuccess, onItemError, onQueueIdle.
Returns queue items, counts, aggregate progress, enqueue, enqueueSafe, cancellation, clear, and reset methods.
useConvexStorageUrl
useConvexStorageUrl(getUrlQuery, storageId, { auth? })Returns ComputedRef<string | null>. The default auth mode is none; private URL queries normally use required.