Skip to main content

Choose Your Path

Start with Nuxt, plain Vue/Vite, Better Auth, or the optional MCP resource boundary.

Start with the smallest path that proves the integration you need.

New Nuxt and Convex app

Follow the complete golden path:

  1. Install Better Convex Nuxt.
  2. Render a real-time page.
  3. Add a mutation.
  4. Add authentication only if the product needs it.

The first three steps omit convex.auth. Omission means a Convex-only build, keeping the initial setup focused on Nuxt, Convex, SSR, and live data.

Existing Nuxt and Convex app

Start with installation, then replace one existing integration path at a time.

Before removing your current client plugin, identify who currently owns:

  • client construction and teardown;
  • SSR data and hydration;
  • authentication tokens;
  • subscriptions;
  • server-side calls.

Do not keep the old client path beside Better Convex Nuxt after the replacement works. Two client owners create duplicate subscriptions and conflicting auth lifecycle.

Nuxt, Convex, and Better Auth

Complete the public query and mutation first. Then follow:

  1. Add authentication.
  2. Protect data.

Authentication is enabled only by an explicit convex.auth object with an exact origin. Omit auth for a Convex-only app; auth: false exists only to erase inherited auth configuration in a Nuxt layer.

Plain Vue or Vite

Use @lupinum/better-convex-vue when the application does not need Nuxt SSR, Nitro routes, the auth proxy, or serverConvex(). The Vue package owns the same browser query, pagination, mutation, action, identity, and disposal lifecycle used by Nuxt after hydration.

Authentication is provider-neutral in plain Vue. Supply an adapter that owns its provider session and returns short-lived Convex tokens, run anonymously, or attach the token-free runtime from a host application. The browser package never receives Better Auth secrets, cookies, or server signing keys.

Agents and MCP

Add @lupinum/better-convex-mcp only when the application needs an MCP resource server. It is an experimental, separately installed package on the exact stable official SDK. Tools and resources are explicit; application Convex functions remain the authorization and effect boundary.

The @lupinum/better-convex-vue/mcp-app entry is a separate experimental progressive enhancement for capable hosts. Ordinary Vue applications do not install its SDK.

Start from a maintained example

The repository contains focused starters:

  • starters/public for a public real-time todo app
  • starters/team for a production-shaped Better Auth organization/team application

Use the public starter to learn the runtime. Use the team starter when you need the full local Better Auth component, product authorization, user projection, and organization workflows.