API Surface

Generated reference of auto-imported composables, server helpers, and global auth components.

This page is generated from module entrypoints and runtime component files.

Source of truth:

This reference answers:

Which APIs are auto-imported?
Which Nuxt aliases are registered?
What is each API for?
Where is the best guide for examples and deeper usage?

Regenerate this page with:

bash

node scripts/generate-api-surface.mjs

Nuxt Aliases

Alias	Points To	Supported Contexts
`#convex/api`	Your app's `convex/_generated/api`	Vue components, composables, route middleware, Nitro server routes, tests
`#convex/server`	`better-convex-nuxt` server exports	Nitro server routes and Convex-adjacent server utilities

Use #convex/api for generated Convex functions:

import { api } from '#convex/api'

Before Convex codegen creates convex/_generated/api, this alias points to a typed placeholder that keeps imports working and fails with a codegen message if accessed.

Published Package Entries

Import Specifier	Runtime Exports	Type Exports
`better-convex-nuxt`	`default`	`BaseAuthClient`, `ConvexAuthMode`, `ConvexAuthOptions`, `ConvexAuthClientRegistry`, `ConvexAuthStatus`, `ConvexCallErrorKind`, `ConvexClientHandle`, `ConvexRuntimeConfig`, `InferRegisteredConvexAuthClient`, `ModuleOptions`, `ServerConvexOptions`, `UseConvexAuthReturn`, `UseConvexMutationOptions`, `UseConvexPaginatedQueryOptions`, `UseConvexQueryOptions`
`better-convex-nuxt/errors`	`ConvexCallError`, `normalizeConvexError`, `isSerializedConvexCallError`	`CallResult`, `ConvexCallErrorKind`, `ConvexCallErrorInput`, `SerializedConvexCallError`
`better-convex-nuxt/auth-client`	`defineConvexAuthClient`	`BaseAuthClient`, `ConvexAuthClientDefinition`, `ConvexAuthClientRegistry`, `InferRegisteredConvexAuthClient`
`better-convex-nuxt/server`	`serverConvex`, `createClassifiedConvexFetch`, `normalizeServerConvexBoundaryError`, `exchangeConvexToken`, `normalizeSiteUrl`	`ServerConvexCaller`, `ServerConvexOptions`, `ConvexCredential`, `ConvexTokenExchangeResult`
`better-convex-nuxt/server/createUserSyncTriggers`	`createUserSyncTriggers`	`BetterAuthUserDocLike`, `CreateUserSyncTriggersOptions`, `UserSyncRebuildResult`

Use #convex/server when an explicit server import is clearer than relying on Nuxt auto-imports, or for exports that are intentionally not auto-imported:

import { serverConvex } from '#convex/server'

createUserSyncTriggers runs inside your convex/ functions, where Nuxt aliases do not exist. Import it from its dedicated subpath instead:

import { createUserSyncTriggers } from 'better-convex-nuxt/server/createUserSyncTriggers'

useConvexAuth, useConvexUser, and the global auth components are always available. With auth: false, they expose the documented disabled-auth state without loading Better Auth. The typed Better Auth client for an enabled build is defined with defineConvexAuthClient from better-convex-nuxt/auth-client and read through useConvexAuth().client.

Name	Kind	Purpose	Learn More
`defineSharedConvexQuery`	Helper	Defines a reusable shared query contract for multiple consumers.	Guide
`deleteFromPaginatedQuery`	Helper	Optimistically removes an item from a paginated query cache.	Guide
`deleteFromQuery`	Helper	Optimistically removes an item from a regular query cache.	Guide
`insertAtBottomIfLoaded`	Helper	Optimistically inserts an item at the end of paginated data when loaded.	Guide
`insertAtPosition`	Helper	Optimistically inserts an item at a custom position in paginated data.	Guide
`insertAtTop`	Helper	Optimistically inserts an item at the top of paginated data.	Guide
`setQueryData`	Helper	Replaces cached query data with a new value.	Guide
`updateAllQueries`	Helper	Applies an updater across multiple cached query results.	Guide
`updateInPaginatedQuery`	Helper	Optimistically updates matching items across paginated query pages.	Guide
`updateQuery`	Helper	Applies an updater to one cached query result.	Guide
`useConvex`	Composable	Returns the stable replacement-safe handle for imperative Convex calls.	Guide
`useConvexAction`	Composable	Runs Convex actions with reactive status and error handling.	Guide
`useConvexAuth`	Composable	Tracks auth state and user/session information in Nuxt.	Guide
`useConvexConfig`	Composable	Auto-imported runtime API provided by this module.	Guide
`useConvexConnectionState`	Composable	Observes live WebSocket connection state to Convex.	Guide
`useConvexFileUpload`	Composable	Uploads files to Convex storage with progress tracking.	Guide
`useConvexMutation`	Composable	Runs Convex mutations with status, errors, and optimistic hooks.	Guide
`useConvexPaginatedQuery`	Composable	Fetches and paginates query results with real-time updates.	Guide
`useConvexQuery`	Composable	Fetches reactive query data with SSR and subscription support.	Guide
`useConvexStorageUrl`	Composable	Resolves Convex file storage IDs to usable URLs.	Guide
`useConvexUploadQueue`	Composable	Queues and coordinates concurrent file uploads.	Guide
`useConvexUser`	Composable	Seeds from session user, then upgrades to canonical user/profile data.	Guide

Server Auto-Imports

Name	Kind	Purpose	Learn More
`exchangeConvexToken`	Server helper	Exchanges a cookie/bearer credential for a Convex JWT (never-throwing outcome).	Guide
`serverConvex`	Server helper	Creates a request-scoped server caller with query/mutation/action for server routes and handlers.	Guide

Global Auth Components

Name	Kind	Purpose	Learn More
`<ConvexAuthenticated>`	Component	Renders slot content only for authenticated users.	Guide
`<ConvexAuthError>`	Component	Renders slot content when auth resolves with an error.	Guide
`<ConvexAuthLoading>`	Component	Renders slot content while auth state is still loading.	Guide
`<ConvexUnauthenticated>`	Component	Renders slot content only for signed-out users.	Guide

Report an issue

API Surface

Nuxt Aliases

Published Package Entries

Composable Auto-Imports

Server Auto-Imports

Global Auth Components