Glossary
The terms these docs use for Better Convex Nuxt concepts and states.
Action
A Convex function for work that calls external services or needs a runtime that queries and mutations do not have. Do not use actions for ordinary database writes.
Application
Your Nuxt or Vue application.
Auth mode
The auth option of a query or server call: required, optional, or none. It decides whether the call waits for the signed-in user and runs as that user.
Auth proxy
The /api/auth/* Nitro route that the module adds. It forwards Better Auth requests from the browser to Convex, so the session cookie stays on your Nuxt origin.
Call status
The status of a query, mutation, or action: idle, pending, success, or error.
Convex identity
The user that a Convex function sees in ctx.auth. It comes from the Convex session token. Read the live user with auth.getUser(ctx) or auth.requireUser(ctx); these also check that the session still exists.
Convex function
A query, mutation, action, or HTTP action in your convex/ folder.
Convex session token
The short-lived token (15 minutes) that signs the Convex client in as the current user. The module gets a new one while the session lasts. It is not the session cookie and not an OAuth access token.
Hydration
Vue attaching client behavior to server-rendered HTML. Query composables start from the server result in the Nuxt payload.
Identity generation
A counter that changes when the signed-in user changes. Query results and pending calls from one generation never reach the next.
MCP principal
The principal value that the MCP handler passes to configureServer. With Better Auth, it is a BetterConvexMcpPrincipal: the user, OAuth client, scopes, and grant of one verified OAuth access token. Pass it to internal Convex functions and check it there with auth.requireMcpPrincipal.
Module
The @lupinum/better-convex-nuxt Nuxt module.
Mutation
A Convex function that reads and writes Convex data in one transaction. Use mutations for database changes.
Nuxt payload
Data that Nuxt sends with server-rendered HTML and reuses in the browser during hydration.
OAuth access token
The short-lived bearer token (ten minutes) that an MCP host sends to your /mcp endpoint. Your application issues it after the person gives consent. It is not the session cookie and not a Convex session token.
Optimistic update
A temporary local change to a query result, applied before the server confirms a mutation. Convex removes it if the mutation fails.
Package
One published Better Convex package: @lupinum/better-convex-nuxt, @lupinum/better-convex-vue, or @lupinum/better-convex-mcp.
Paginated query status
The status of a paginated query. It describes the first page only and uses the same values as a query. Later pages report through isLoadingMore, canLoadMore, and isExhausted.
Query
A read-only Convex function. The browser subscribes to its result and receives new values when the data changes.
Query block reason
The blockedBy value of a query or paginated query: 'skip' for skipped arguments, 'manual' for an immediate: false query that has not started, 'auth' while the query waits for or lacks the required user, and null when the query may run. The server render and the browser report the same value.
Real-time subscription
A browser WebSocket listener for one Convex query and its arguments. It updates the composable when Convex sends a new result.
Server call
A query, mutation, or action that a Nitro handler runs through serverConvex(event). It does not create a browser subscription.
Server-side rendering (SSR)
Nuxt rendering a page on the server for an incoming request. Queries can run during this step.
Session
The Better Auth session stored in Convex. The browser holds it as a cookie on your Nuxt origin. It is the source of truth for who is signed in.
Signing key
The RS256 key that signs Convex session tokens and OAuth access tokens. Create the first one with auth:ensureSigningKey and rotate it with auth:rotateSigningKey.
Stale data
The last successful result, kept visible on purpose while new arguments load. isStale is true during that time. Stale data never crosses to another user.
Trusted client IP header
The request header, set in convex.auth.trustedClientIpHeader, that your host overwrites with the client's IP address. The auth proxy signs this address and sends it to Convex for rate limiting.
User projection
An application table copied from Better Auth user data, for fields or indexes that the auth component does not have. You can rebuild it from Better Auth at any time.