Server API

Imports

Inside Nuxt server code:

import { serverConvex } from '#convex/server'

Outside Nuxt aliases:

import { serverConvex, exchangeConvexToken } from 'better-convex-nuxt/server'

serverConvex

serverConvex(event: H3Event, options?: ServerConvexOptions): ServerConvexCaller

Options:

interface ServerConvexOptions {
  auth?: 'required' | 'optional' | 'none'
  authToken?: string
  credential?: { type: 'cookie'; value: string } | { type: 'bearer'; value: string }
}

The caller exposes:

getToken(): Promise<string | null>
query(query, args): Promise<Result>
mutation(mutation, args): Promise<Result>
action(action, args): Promise<Result>

No-argument Convex functions still receive {}.

exchangeConvexToken

await exchangeConvexToken({
  siteUrl,
  credential: { type: 'cookie', value: cookieHeader },
})

It returns a never-throwing ConvexTokenExchangeResult for network/upstream outcomes. Invalid argument or credential shape can throw synchronously before network access.

Prefer serverConvex for normal Nitro calls.

Boundary helpers

createClassifiedConvexFetch and normalizeServerConvexBoundaryError preserve the package error classification at custom integration boundaries. They are not general HTTP clients.

normalizeSiteUrl validates the token-exchange site origin.

createUserSyncTriggers

Import inside Convex code:

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

Options: table, index, optional authIdField, createDoc, optional patchDoc, optional rebuildDoc.

Returns user onCreate, onUpdate, onDelete, and rebuild handlers for a derived projection. Better Auth remains canonical.