Module Configuration

Reference for every supported option under the nuxt.config.ts convex key.

nuxt.config.ts

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

Core

Option	Type	Default
`url`	`string`	`NUXT_PUBLIC_CONVEX_URL` or `CONVEX_URL`
`siteUrl`	`string`	Public env value or derived standard `.convex.site` URL
`auth`	`false \| ConvexAuthOptions`	Omitted; authentication is not installed
`logging`	`false \| 'info' \| 'debug'`	`false`

url is the Convex deployment URL. siteUrl is the HTTP Actions origin used for auth exchange.

Authentication

auth: {
  origin: process.env.SITE_URL ?? 'http://localhost:3000',
  client: '~/convex-auth.ts',
  trustedClientIpHeader: process.env.BCN_AUTH_TRUSTED_CLIENT_IP_HEADER,
  redirectTo: '/auth/signin',
}

origin is required and is the one exact public Nuxt application origin. It must not contain a path, query, or fragment. client is build-only and never copied into runtime config. The auth proxy path is fixed at same-origin /api/auth; its body bounds, safe return-path preservation, and diagnostics channels are internal invariants rather than module options.

trustedClientIpHeader may be empty only for exact loopback development origins. Every other auth origin must name an ingress-owned header containing exactly one client IP; the ingress must overwrite it rather than append a forwarding chain. Keep the Nuxt origin unreachable to public traffic that bypasses this ingress, or independently authenticate ingress requests there.

Omit auth to exclude Better Auth runtime installation. Use auth: false only in a Nuxt layer that must erase an auth object inherited from another layer. There is no nested enabled flag.

Per-call query policy

Query auth, same-identity stale-data behavior, and the Nuxt-only SSR exception belong on each query call. They are not module configuration.

Full example

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@lupinum/better-convex-nuxt'],
  convex: {
    url: process.env.NUXT_PUBLIC_CONVEX_URL,
    siteUrl: process.env.NUXT_PUBLIC_CONVEX_SITE_URL,
    auth: {
      origin: process.env.SITE_URL ?? 'http://localhost:3000',
      trustedClientIpHeader: process.env.BCN_AUTH_TRUSTED_CLIENT_IP_HEADER,
      redirectTo: '/auth/signin',
    },
    logging: process.env.NODE_ENV === 'development' ? 'info' : false,
  },
})