Skip to main content

Limitations and trade-offs

Know the costs and unsupported cases before you adopt the module.

The module makes fixed choices so that SSR, live data, and auth work together. These choices have costs.

A server-rendered live query runs twice

By default, a query runs:

  1. Once over HTTP during server rendering.
  2. Once as a WebSocket subscription in the browser.

The first run produces the HTML. The second keeps the data live. The Convex dashboard shows both runs.

Turn off server rendering for data that only the browser needs:

ts
useConvexQuery(api.notifications.list, {}, { server: false })

Every useConvexQuery subscribes in the browser. For a one-time read, call useConvex().query(...) or serverConvex in a Nuxt server route.

Nuxt auth uses Better Auth

The Nuxt module supports Better Auth only. Another auth provider needs your own integration.

The plain Vue package accepts any provider through an auth adapter. See plain Vue and Vite.

Omit convex.auth when the app has no sign-in. The build then contains no auth plugins, proxy, middleware, or Better Auth code. Use auth: false only to remove auth that a Nuxt layer added.

You write the permission checks

The module knows who the user is. It does not know whether that user may edit a project or read a document.

Check permissions inside Convex functions. Route middleware and hidden buttons only change the UI.

Some Better Auth plugins need extra setup

The module supports the organization, two-factor, and email OTP plugins, and the OAuth provider plugin for MCP. It rejects every other Better Auth plugin, for example admin and API keys. See Better Auth plugin support.

The organization and two-factor plugins change the auth database schema. They need a matching server option, a regenerated schema, and a typed client. Run better-convex-nuxt auth schema to regenerate the schema. See Better Auth plugins.

The raw Convex client is not available

useConvex() returns only query, mutation, action, and onUpdate. It does not return setAuth, clearAuth, connectionState, or close.

The module replaces the client when the user changes. A kept reference to an old client would break. Use useConvexConnectionState() to read the connection state.

Query data belongs to the component

Each query composable keeps its own data for the component that created it. There is no shared cache across requests or users.

Convex is the source of truth for server data. Use Pinia or local state only for UI state, not for copies of Convex documents.

Better Auth versions are pinned

better-auth, @better-auth/core, and @better-auth/oauth-provider must be exactly 1.7.16. Nuxt and Convex accept a range. Upgrade Better Auth only together with a new version of this module.

Auth needs a new database

The auth component does not import users from another auth setup. Start with an empty component database, registered as betterAuth.

OAuth for MCP supports one setup

The OAuth provider for MCP hosts supports:

  • preregistered clients, both confidential and public;
  • authorization code with PKCE S256 and explicit consent;
  • one resource per token and short-lived access tokens;
  • refresh tokens tied to the session that gave consent.

It does not support dynamic client registration, client credentials, DPoP, or tokens for several resources. See delegated OAuth and MCP.

Read release compatibility before you override any version.

Company sign-in supports one OIDC provider

The oidc option signs users in through one OpenID Connect identity provider (IdP). It has these limits:

  • one IdP per deployment;
  • no SAML;
  • logout ends all sessions of a user, not one IdP session;
  • no front-channel logout;
  • no token exchange;
  • IdP roles and groups reach the app only through oidc.onSignIn, so a change at the IdP applies at the user's next sign-in;
  • client authentication with a client secret only (no private_key_jwt or mTLS);
  • Microsoft Entra ID with several tenants is not supported;
  • the ID token must carry an email that the IdP marks as verified (email_verified, or xms_edov on Microsoft Entra ID);
  • ID tokens signed with HMAC (HS256) are refused;
  • a changed email at the IdP is not copied to the user;
  • changing the issuer unlinks every IdP user;
  • a user who signs in through the IdP has no other way to sign in while the IdP is down;
  • with open password or email-code sign-up, anyone can register an employee's address before the employee first signs in through the IdP. The employee then gets account_not_linked. Set disableSignUp on emailAndPassword and emailOTP, or turn them off, when you use oidc;
  • the liveness check needs refresh tokens. On an IdP whose refresh tokens outlive the IdP session, it does not catch a sign-out at the IdP;
  • with session.cookieCache, Better Auth's own endpoints accept a logged-out session for up to maxAge.

See company sign-in.