Module Configuration

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

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['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`	Auth installed with defaults
`logging`	`false \| 'info' \| 'debug'`	`false`

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

Authentication

auth: {
  client: '~/convex-auth.ts',
  proxy: {
    maxRequestBodyBytes: 1_048_576,
    maxResponseBodyBytes: 1_048_576,
    trustedClientIpHeader: '',
  },
  debug: {
    authFlow: false,
    clientAuthFlow: false,
    serverAuthFlow: false,
  },
  routeProtection: {
    redirectTo: '/auth/signin',
    preserveReturnTo: true,
  },
}

client is build-only and never copied into runtime config. The auth proxy path is fixed at same-origin /api/auth.

Set auth: false to remove Better Auth runtime installation. There is no nested enabled flag.

Query defaults

defaults: {
  server: true,
  subscribe: true,
  waitTimeoutMs: 10_000,
}

Option	Normalization
`server`	Boolean default for regular and paginated queries
`subscribe`	Boolean default for regular and paginated queries
`waitTimeoutMs`	Non-negative finite integer; invalid values use 10 seconds; `0` waits indefinitely

Query auth mode is not a module default. It remains optional unless the query specifies another mode.

Upload defaults

upload: {
  maxConcurrent: 3,
}

The value is truncated to a positive integer. Invalid input uses three; values below one normalize to one.

Full example

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['better-convex-nuxt'],
  convex: {
    url: process.env.NUXT_PUBLIC_CONVEX_URL,
    siteUrl: process.env.NUXT_PUBLIC_CONVEX_SITE_URL,
    auth: {
      routeProtection: {
        redirectTo: '/auth/signin',
        preserveReturnTo: true,
      },
    },
    defaults: {
      server: true,
      subscribe: true,
      waitTimeoutMs: 10_000,
    },
    upload: { maxConcurrent: 3 },
    logging: process.env.NODE_ENV === 'development' ? 'info' : false,
  },
})

Report an issue