Mental Model

Understand which system owns rendering, data, sessions, coordination, and authorization.

Better Convex Nuxt connects systems that retain separate responsibilities. The integration stays predictable when each important fact has one owner.

Five owners

Owner	Canonical responsibility
Nuxt	App instances, SSR, payloads, hydration, routes, runtime config, and teardown
Convex	Backend functions, data consistency, transport, subscriptions, and query deduplication
Better Auth	Session truth, cookies, authentication operations, and auth plugins
Better Convex Nuxt	Deterministic coordination between Nuxt, Convex, and Better Auth
Your application	Product authorization, roles, redirects, domain errors, and workflows

The module does not copy those responsibilities into a new platform. It translates between them.

One request crosses the owners

Browser request
  → Nuxt creates the request/app context
  → Better Auth resolves the session when auth is enabled
  → Better Convex Nuxt selects the query identity and execution path
  → Convex executes the backend function
  → Nuxt renders and serializes the result
  → Better Convex Nuxt continues with a browser subscription

The result moves between systems. Ownership does not.

Sources of truth

Server-backed data

Convex is the source of truth. A query result in a Vue ref is a view of that data. An optimistic update is a temporary local view that Convex will confirm or roll back.

Do not mirror posts, tasks, or memberships into another store merely to make them “global.” Use a shared query definition when multiple components need one Vue-visible query state.

Session

Better Auth is the source of truth for whether a session exists and for its session user fields. Better Convex Nuxt observes that state and coordinates the Convex identity.

Product authorization

Your Convex functions are the source of truth for access. A Nuxt middleware redirect cannot protect a backend function.

Runtime configuration

The module normalizes build options into one per-app public runtime configuration. Server-only secrets remain in private Nitro/request state.

A useful rule

Ask “who can know this fact correctly?” before adding state.

Convex can know whether a document belongs to an organization.
Better Auth can know whether a session is valid.
Nuxt can know which request is rendering.
Better Convex Nuxt can know when the Convex client must change identity.
The application can know whether editor may publish a document.

Placing a fact with the wrong owner creates duplicated state or a security gap.

Next, follow a complete request lifecycle.

Report an issue