Server and client boundaries

The package has explicit entry points because browser, Nuxt, server, and framework-free code have different dependencies and secret boundaries.

Boundary map

Vue component
  → auto-imported composables
  → current browser client
  → Convex function

Nitro handler
  → #convex/server or @lupinum/better-convex-nuxt/server
  → request-scoped HTTP client
  → Convex function

Convex function
  → @lupinum/better-convex-nuxt/better-auth/server
  → auth.getUser(ctx), auth.requireUser(ctx)

Framework-free code
  → @lupinum/better-convex-nuxt/errors

Root package

@lupinum/better-convex-nuxt exports the Nuxt module and stable public types. Register it in nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@lupinum/better-convex-nuxt'],
})

The module auto-imports the composables. There is no separate /composables package path and no auth UI component.

Generated Convex API

Use #convex/api for the consumer application's generated Convex function references:

import { api } from '#convex/api'

The module points this alias at convex/_generated/api. If generation has not run, a diagnostic placeholder produces a clear type error rather than silently erasing types.

Server entry

Use #convex/server inside a Nuxt application or import the published entry explicitly:

import { serverConvex } from '#convex/server'

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

serverConvex creates a request-scoped caller. Its query, mutation, and action calls do not hydrate browser composable state.

The same entry exports getConvexUser and requireConvexUser, which read the request's signed-in user, and toConvexH3Error, which turns an error into a safe H3 response. The module auto-imports all four in Nitro code.

Error entry

@lupinum/better-convex-nuxt/errors contains the framework-free error contract:

import {
  ConvexCallError,
  isConvexCallError,
  normalizeConvexError,
} from '@lupinum/better-convex-nuxt/errors'

It has no Nuxt, Vue, Nitro, browser, or Node runtime dependency.

Auth-client entry

@lupinum/better-convex-nuxt/better-auth/client describes the Better Auth client plugins. The module reads this file at build time:

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

The definition lists plugins and gives their methods types. It does not create another Better Auth client.

Keep secrets on the server

useConvexConfig() exposes only the resolved deployment url and siteUrl. Cookies, bearer credentials, exchanged tokens, and server-only request state must not move into public config, page payloads, or client logs.

Use a Nitro route when the operation needs a server-held secret, webhook verification, or server-owned API contract. Call Convex directly from the browser for ordinary application queries and mutations.