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 better-convex-nuxt/server
  → request-scoped HTTP client
  → Convex function

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

Root package

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

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

Client composables and auth components are auto-imported by the module. They are not exposed through a separate /composables package path.

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 'better-convex-nuxt/server'

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

Error entry

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

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

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

Auth-client entry

better-convex-nuxt/auth-client defines the type-only client configuration discovered at build time:

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

The definition describes plugins and inference. It does not instantiate another Better Auth client.

Keep secrets on the server

Public runtime config contains deployment URLs and normalized public behavior. 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.