Module configuration
Every option under the convex key in nuxt.config.ts, and the convexAuth page metadata.
Configure the module under the convex key. The type is ModuleOptions.
export default defineNuxtConfig({
modules: ['@lupinum/better-convex-nuxt'],
convex: {},
})Core
| Option | Type | Default |
|---|---|---|
url | string | NUXT_PUBLIC_CONVEX_URL, then CONVEX_URL |
siteUrl | string | NUXT_PUBLIC_CONVEX_SITE_URL, then CONVEX_SITE_URL, then the .convex.site URL for url |
auth | false | ConvexAuthOptions | Not set: authentication is off |
logging | false | 'info' | 'debug' | false |
client | object | See browser client |
server | object | See server limits |
url is the Convex deployment URL, for example https://happy-otter-123.convex.cloud. siteUrl is the URL of the deployment's HTTP actions, for example https://happy-otter-123.convex.site. The module uses siteUrl to exchange the session for a Convex session token. When you set only url, the module derives siteUrl from it at runtime, so a deploy-time NUXT_PUBLIC_CONVEX_URL also changes siteUrl.
logging: 'info' logs short messages. logging: 'debug' adds timings and details.
Authentication
Authentication is off until you add an auth object:
export default defineNuxtConfig({
modules: ['@lupinum/better-convex-nuxt'],
convex: {
auth: {
origin: process.env.SITE_URL,
trustedClientIpHeader: process.env.BCN_AUTH_TRUSTED_CLIENT_IP_HEADER,
},
},
})| Option | Type | Default | Effect |
|---|---|---|---|
origin | string | Required | The public origin of the Nuxt application |
client | string | Not set | Path to a file that exports defineConvexAuthClient(...) |
trustedClientIpHeader | string | '' | The request header that your proxy or host sets to the client IP |
redirectTo | string | '/auth/signin' | The sign-in page for anonymous visitors on a protected page |
guestRedirectTo | string | '/' | Where a signed-in visitor goes from a convexAuth: 'guest' page |
defaultQueryAuth | 'optional' | 'required' | 'none' | 'optional' | The auth mode of a query that does not set one |
routes | 'public' | 'protected' | 'public' | Whether a page without convexAuth metadata needs a signed-in user |
ssr | boolean | true | Whether server rendering reads the session |
origin is one exact origin, such as https://app.example.com. It must not contain a path, query, or fragment. The examples read it from SITE_URL. Set SITE_URL in every environment, including SITE_URL=http://localhost:3000 in .env.local for local development. The module throws an error when origin is empty.
client is read only at build time. Use it to add Better Auth client plugins. The module does not copy it into the runtime configuration. convex.auth as a whole is build-time configuration: the build includes or leaves out authentication. Do not override it with NUXT_PUBLIC_CONVEX_AUTH* environment variables; change nuxt.config and rebuild.
trustedClientIpHeader names a header that contains exactly one client IP address. Your proxy or host must overwrite this header on every request. It must not append to a list, such as X-Forwarded-For. The module uses the IP address for rate limiting. You may leave it empty only when origin is localhost, 127.0.0.1, or [::1]. Make sure that public traffic cannot reach Nuxt without passing through that proxy. See environment variables.
redirectTo and guestRedirectTo must be local paths that start with one /. The module rejects other values at build time and at runtime.
defaultQueryAuth applies to useConvexQuery and useConvexPaginatedQuery. The auth option of a call always wins. The server render and the browser use the same value. It does not apply to serverConvex.
ssr: false renders every page as an anonymous visitor, so a shared cache can store the HTML. The route rule convex: { ssrAuth } sets this per route and wins over ssr. See cacheable public pages.
The auth proxy path is always /api/auth on your own origin. You cannot change it.
Set auth: false only in a Nuxt layer that must turn off an auth object from another layer. There is no enabled flag.
Page metadata
With authentication on, each page can set convexAuth in definePageMeta:
<script setup lang="ts">
definePageMeta({ convexAuth: true })
</script>| Value | Effect |
|---|---|
true | The page needs a signed-in user. Anonymous visitors go to redirectTo. |
{ redirectTo: '/login' } | The page needs a signed-in user. Anonymous visitors go to this route. |
'guest' | The page is for signed-out visitors, such as a sign-in page. Signed-in visitors go to the ?redirect= path or to guestRedirectTo. |
false | The page is public, even when routes is 'protected' |
| Not set | The page follows routes |
The route middleware adds the current path as ?redirect= when it sends a visitor to the sign-in page. Read it with useConvexAuthReturnTo.
Route middleware only controls navigation. It does not protect data. Check the user in every Convex function that returns private data.
Route rules
With authentication on, the module reads one Nitro route rule:
routeRules: {
'/**': { convex: { ssrAuth: false } },
}| Rule | Type | Effect |
|---|---|---|
convex.ssrAuth | boolean | Whether server rendering reads the session for matching pages |
Browser client
client.connect sets when the browser runtime starts. The other client options go to every browser ConvexClient that the module creates. This includes the client for auth: 'none' queries.
client: {
connect: 'eager',
verbose: false,
skipConvexDeploymentUrlCheck: false,
unsavedChangesWarning: false,
}| Option | Type | Default | Effect |
|---|---|---|---|
connect | 'eager' | 'on-demand' | 'eager' | Start the Convex and Better Auth clients with the app, or on demand |
verbose | boolean | false | Log Convex client debug output in the browser console |
skipConvexDeploymentUrlCheck | boolean | false | Accept a self-hosted deployment URL that does not end in .convex.cloud |
unsavedChangesWarning | boolean | false | Ask before the page closes while mutations are still pending |
The build fails for any other client option. The module controls authentication, logging, and client replacement. In Vue without Nuxt, pass the same options except connect, plus webSocketConstructor, as createBetterConvex({ convexUrl, clientOptions }).
connect: 'on-demand' loads no Convex or Better Auth client code and opens no WebSocket until useConvexActivation().activate() runs, or until the route middleware reaches a page with convexAuth metadata. It is a build option only. See start the client on demand.
experimental.keepAlive
Keep query subscriptions open for a while after the last component leaves. Returning to the same query and arguments can then show the current data at once, while the subscription is still retained. This option is off by default. It is experimental and is not covered by semantic versioning.
convex: {
experimental: {
keepAlive: { ms: 60_000, max: 30 },
},
}Start with ms: 60_000 and max: 30. Both values must be positive safe
integers. ms is the retention time in milliseconds. max limits retained
subscription handles; when the limit is exceeded, the oldest is released first.
Convex shares identical queries within one client, but each retained query is
re-run by Convex when its data changes. Retention therefore uses memory and can
increase backend work even when no component displays the result.
A user change drops all retained subscriptions immediately. Application
disposal also releases them. Queries that use the dedicated anonymous
auth: 'none' transport are not retained.
Server limits
server limits the Convex HTTP calls during server rendering and from serverConvex.
server: {
maxResponseBytes: 1_048_576,
queryTimeoutMs: 8_000,
}| Option | Type | Default | Effect |
|---|---|---|---|
maxResponseBytes | number | 1048576 | Largest accepted Convex HTTP response body, in bytes |
queryTimeoutMs | number | 8000 | Time limit for one Convex HTTP query, in milliseconds |
Both values must be positive safe integers; queryTimeoutMs is at most 2,147,483,647. A larger response fails with a transport error and code RESPONSE_TOO_LARGE. A query that takes longer fails with code TIMEOUT. Mutations have a fixed 15-second limit, and actions a fixed 60-second limit.
To change the limits at deploy time, set NUXT_PUBLIC_CONVEX_SERVER_MAX_RESPONSE_BYTES and NUXT_PUBLIC_CONVEX_SERVER_QUERY_TIMEOUT_MS. These values are public runtime configuration, not secrets. An invalid value fails the build. An invalid deploy-time value fails every request that reads the configuration.
Full example
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,
trustedClientIpHeader: process.env.BCN_AUTH_TRUSTED_CLIENT_IP_HEADER,
redirectTo: '/auth/signin',
},
logging: process.env.NODE_ENV === 'development' ? 'info' : false,
server: {
queryTimeoutMs: 5_000,
},
},
})