API Surface

Generated reference of auto-imported composables, server helpers, aliases, and package entries.

This page is generated from the reviewed module and package entrypoint registries.

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
`#convex/auth-client`	The configured Better Auth client definition	Auth-enabled builds only

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
`@lupinum/better-convex-nuxt`	`default`	`ConvexAuthMode`, `ConvexAuthOptions`, `ConvexAuthStatus`, `ConvexCallStatus`, `ConvexClientHandle`, `ConvexRuntimeConfig`, `ModuleOptions`, `NuxtConvexPaginatedQuery`, `NuxtConvexQuery`, `OptimisticUpdate`, `UploadProgressInfo`, `UploadStatus`, `UploadUrlMutation`, `UseConvexAuthReturn`, `UseConvexCall`, `UseConvexFileUploadOptions`, `UseConvexFileUploadReturn`, `UseConvexMutationOptions`, `UseConvexPaginatedQueryOptions`, `UseConvexPaginatedQueryState`, `UseConvexQueryOptions`, `UseConvexQueryParameters`, `UseConvexQueryState`
`@lupinum/better-convex-nuxt/errors`	`ConvexCallError`, `normalizeConvexError`, `isSerializedConvexCallError`	`ConvexCallErrorKind`, `ConvexCallErrorInput`, `SerializedConvexCallError`
`@lupinum/better-convex-nuxt/auth-client`	`defineConvexAuthClient`	`BaseAuthClient`, `ConvexAuthClientDefinition`, `ConvexAuthClientRegistry`, `InferRegisteredConvexAuthClient`, `IntegratedAuthClient`
`@lupinum/better-convex-nuxt/convex-auth`	`convexAuth`, `createBetterAuthMcpAccessVerifier`, `createAuthComponent`, `createUserProjectionTriggers`, `defineAuthAdapterFunctions`, `getConvexAuthProvider`, `requireAuthOrigin`, `verifyOAuthBearerToken`	`AuthComponentTriggers`, `AuthCtx`, `AuthFunctions`, `BetterAuthMcpAccessVerifierOptions`, `BetterAuthUserProjectionSource`, `CreateAuth`, `CreateUserProjectionTriggersOptions`, `VerifyOAuthBearerTokenOptions`
`@lupinum/better-convex-nuxt/convex-auth/convex.config`	`default`	—
`@lupinum/better-convex-nuxt/convex-auth/_generated/component.js`	—	`ComponentApi`
`@lupinum/better-convex-nuxt/convex-auth/test`	`default`, `register`	—
`@lupinum/better-convex-nuxt/server`	`serverConvex`	`ServerConvexCaller`, `ServerConvexOptions`

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'

createUserProjectionTriggers runs inside your convex/ functions. Import it from the Better Auth integration subpath:

import { createUserProjectionTriggers } from '@lupinum/better-convex-nuxt/convex-auth'

Core composable auto-imports

These composables are available in every build. Omitting convex.auth keeps Better Auth, its proxy, its middleware, its page metadata, and useConvexAuth out of the application surface.

Name	Kind	Purpose	Learn More
`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
`useConvexAttachment`	Composable	Returns the frozen token-free runtime boundary for an embedded Vue application.	Guide
`useConvexConfig`	Composable	Returns the readonly public Convex deployment URLs.	Guide
`useConvexConnectionState`	Composable	Observes the exact live Convex transport state.	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	Returns one reactive, SSR-aware pagination lifecycle.	Guide
`useConvexQuery`	Composable	Returns one reactive SSR-to-realtime query lifecycle.	Guide

useConvexQuery accepts auth, keepPreviousData, and Nuxt's server option. Its state is data, status, pending, error, isStale, and refresh(). These option and state lists are exhaustive.

useConvexPaginatedQuery requires a positive initialNumItems. Its state is data, status, isLoading, canLoadMore, error, isStale, loadMore(), and refresh().

Auth-enabled auto-imports

Auth is an explicit opt-in:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@lupinum/better-convex-nuxt'],
  convex: {
    auth: {
      origin: process.env.SITE_URL ?? 'http://localhost:3000',
      trustedClientIpHeader: process.env.BCN_AUTH_TRUSTED_CLIENT_IP_HEADER,
    },
  },
})

Only an auth-enabled build auto-imports the following API. Define its typed Better Auth client with defineConvexAuthClient from @lupinum/better-convex-nuxt/auth-client, then access the integrated client through useConvexAuth().client.

Name	Kind	Purpose	Learn More
`useConvexAuth`	Composable	Tracks auth state and user/session information in Nuxt.	Guide

Render auth UI with ordinary Vue conditionals over status, isPending, and error. The module does not register auth UI components.

Server auto-imports

Name	Kind	Purpose	Learn More
`serverConvex`	Server helper	Creates a request-scoped server caller with query/mutation/action for server routes and handlers.	Guide