API surface

This page lists the auto-imported composables, server helpers, aliases, and package entries. The source of truth is src/module-api-surface.ts for auto-imports, each package's exports in package.json, and the type declarations that ship with each package. Update this page in the same pull request that changes one of them.

Nuxt aliases

Use #convex/api for generated Convex functions:

import { api } from '#convex/api'

Before Convex creates convex/_generated/api, this alias points to a placeholder. Imports still compile. Reading a function from it throws an error that tells you to run Convex codegen.

Published package entries

Import from #convex/server when you want an explicit import instead of a Nitro auto-import, or when the export is not auto-imported:

import { requireConvexUser, serverConvex } from '#convex/server'

Code in your convex/ folder imports the Better Auth helpers, such as createUserProjectionTriggers, from the better-auth/server entry:

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

Core composable auto-imports

Every build auto-imports these composables. When you omit convex.auth, the module does not install Better Auth, the auth proxy, the auth route middleware, the convexAuth page metadata, or useConvexAuth.

useConvexQuery options: auth, keepPreviousData, immediate, server, and lazy. It returns data, status, pending, error, isStale, blockedBy, execute(), and refresh().

useConvexPaginatedQuery options: initialNumItems, initialCursor, auth, keepPreviousData, immediate, server, and lazy. initialNumItems is required and must be a positive integer. It returns data, status, pending, error, isStale, blockedBy, canLoadMore, isLoadingMore, isExhausted, loadMore(), execute(), refresh(), and reset(). status and pending describe the first page only. loadMore() returns a Promise that never rejects.

In plain Vue, the query options do not include server or lazy.

useConvexMutation returns mutate(), data, status, pending, error, and reset(). useConvexAction returns run(), data, status, pending, error, and reset(). Destructure the result: const { mutate, pending, error } = useConvexMutation(api.notes.create).

Auth-enabled auto-imports

Authentication is off until you add a convex.auth object:

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 API below. To add Better Auth client plugins, define the client with defineConvexAuthClient from @lupinum/better-convex-nuxt/better-auth/client and set convex.auth.client to that file. Use the client through useConvexAuth().client.

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

Server auto-imports