Advanced

Module Configuration

Complete reference for all nuxt.config.ts convex options.

All options are set under the convex key in nuxt.config.ts:

nuxt.config.ts

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

  convex: {
    // Options go here
  },
})

Options Reference

Core

Option	Type	Default	Description
`url`	`string`	`undefined`	Convex deployment URL (e.g., `https://your-app.convex.cloud`). Usually set via `CONVEX_URL` env var.
`siteUrl`	`string`	Auto-derived	Convex HTTP Actions URL (e.g., `https://your-app.convex.site`). Auto-derived from `url` by replacing `.convex.cloud` with `.convex.site`. Override for custom domains.

Authentication

Option	Type	Default	Description
`auth`	`ConvexAuthConfigInput`	`{ enabled: true }`	Authentication config. Set `auth.enabled = false` to disable auth features. See Authentication.
`authRoute`	`string`	`'/api/auth'`	Route path for the auth proxy.
`trustedOrigins`	`string[]`	`[]`	Additional trusted origins for CORS on the auth proxy. Supports wildcards (e.g., `'https://preview-*.vercel.app'`).
`skipAuthRoutes`	`string[]`	`[]`	Routes that skip auth checks entirely. Supports globs (`/docs/**`). See Skipping Auth.

Auth Proxy Limits

Option	Type	Default	Description
`authProxy`	`AuthProxyOptions`	`{}`	Request/response body-size limits for the Better Auth proxy route.

nuxt.config.ts

convex: {
  authProxy: {
    maxRequestBodyBytes: 1_048_576,  // 1 MiB
    maxResponseBodyBytes: 1_048_576, // 1 MiB
  },
}

Query Defaults

Option	Type	Default	Description
`defaults`	`QueryDefaults`	`{}`	Default options for `useConvexQuery` and `useConvexPaginatedQuery`. Per-query options override these.

nuxt.config.ts

convex: {
  defaults: {
    server: true,    // Run queries on server during SSR (default)
    subscribe: true, // Enable real-time subscriptions (default)
    auth: 'auto',    // Attach auth token when available (default)
  },
}

Upload

Option	Type	Default	Description
`upload`	`UploadDefaults`	`{}`	Default options for upload composables.

nuxt.config.ts

convex: {
  upload: {
    maxConcurrent: 3,  // Max concurrent uploads for useConvexUploadQueue
  },
}

Caching

Option	Type	Default	Description
`authCache`	`AuthCacheOptions`	`{ enabled: false, ttl: 60 }`	SSR auth token caching. See Performance.

nuxt.config.ts

convex: {
  authCache: {
    enabled: true,
    ttl: 60, // 60 seconds (max)
  },
}

Permissions

Option	Type	Default	Description
`permissions`	`boolean`	`false`	Enable permission composables (`createPermissions` factory). See Permissions.

Logging & Debug

Option	Type	Default	Description
`logging`	`false \| 'info' \| 'debug'`	`false`	Module log level. See Logging.
`debug`	`ConvexDebugOptions`	`{}`	Enable high-verbosity trace logs for specific channels.

nuxt.config.ts

convex: {
  logging: 'info',
  debug: {
    authFlow: false,        // Detailed auth flow logs (both client and server)
    clientAuthFlow: false,  // Client-only auth flow trace
    serverAuthFlow: false,  // Server-only auth flow trace
  },
}

Full Example

nuxt.config.ts

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

  convex: {
    url: process.env.CONVEX_URL,
    // siteUrl: 'https://custom-domain.example.com', // Only if using custom domain

    auth: { enabled: true },
    skipAuthRoutes: ['/', '/pricing', '/docs/**'],

    defaults: {
      server: true,
      subscribe: true,
    },

    upload: {
      maxConcurrent: 3,
    },

    authCache: {
      enabled: true,
      ttl: 60,
    },

    permissions: true,

    logging: process.env.NODE_ENV === 'development' ? 'debug' : false,
  },
})

Logging

Configure module logging for debugging SSR, auth, queries, and real-time subscriptions.

API Surface

Generated reference of auto-imported composables, server helpers, and global auth components.