Server API

Imports

Inside Nuxt server code:

import { serverConvex } from '#convex/server'

Outside Nuxt aliases:

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

serverConvex

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

Options:

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

authToken accepts an already-issued Convex JWT. credential accepts a Better Auth cookie header. Raw Better Auth session tokens are not a public bearer credential. Both explicit-principal forms imply required authentication, so do not add a redundant auth: 'required' field.

The caller exposes:

getToken(): Promise<string | null>
query(query, ...args: OptionalRestArgs<Query>): Promise<Result>
mutation(mutation, ...args: OptionalRestArgs<Mutation>): Promise<Result>
action(action, ...args: OptionalRestArgs<Action>): Promise<Result>

No-argument Convex functions omit the artificial {} argument. Functions with declared arguments still require their generated argument object.

Cookie exchange remains request-bound: use serverConvex(event, { credential: { type: 'cookie', value: cookieHeader } }). The package does not expose a raw cookie-to-token helper because a request-less exchange cannot preserve the trusted client identity used for rate-limit isolation.

createUserProjectionTriggers

Import inside Convex code:

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

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.