Skip to main content

Release compatibility

Install the dependency versions that Better Convex Nuxt is tested with.

Better Convex Nuxt tests authentication with one exact set of Better Auth versions. Install those versions. Treat the peer versions as part of the security setup, not as package-manager noise.

Supported versions

DependencySupported version
Node.js^22.19.0 || ^24.11.0
Nuxt>=4.5.2 <5
Vue (@lupinum/better-convex-vue)>=3.5.0 <4
Convex>=1.42.2 <2
Better Auth1.7.6 exactly, optional peer
@better-auth/core1.7.6 exactly, optional peer
@better-auth/oauth-provider1.7.6 exactly, optional peer
MCP server SDK@modelcontextprotocol/server 2.1.0, installed by @lupinum/better-convex-mcp

The peerDependencies field of each package manifest is the source of truth.

An application without auth installs none of the Better Auth packages. An application with auth installs all three at the exact version:

bash
pnpm add better-auth@1.7.6 @better-auth/core@1.7.6 @better-auth/oauth-provider@1.7.6

The library loads @better-auth/oauth-provider whenever auth is on, even without MCP. Better Auth brings its own Kysely dependency; do not install another copy.

Why the Better Auth versions are exact

Authentication crosses Better Auth cookies, its Convex adapter, the token exchange, the Nuxt request, SSR serialization, and the Convex clients. A Better Auth patch release can change one of those parts. The library allows a new Better Auth version only after its contract, security, browser, and package tests pass with it.

Do not use package-manager overrides to silence a peer conflict in production. Upgrade to a release of Better Convex that supports the new Better Auth version, or stay on the tested versions.

Upgrade Better Convex

  1. Read every changelog entry between your version and the target version. From a 1.0 beta, follow Upgrade to 1.0.
  2. Install the exact peer versions that the target release declares.
  3. Regenerate the local auth schema, if you have one, and then the Convex types.
  4. Run your type checks, backend tests, and browser tests.
  5. Test sign-in, sign-out, session expiry, sign-out in a second tab, switching accounts, SSR hydration, and reconnect.
  6. Test each social provider, MCP host connection, and account recovery flow against real infrastructure.

Fixes for Better Auth 1.7.6

The library contains two internal, tested fixes for gaps in Better Auth 1.7.6: a URL.canParse replacement for the Convex runtime, used by the OAuth provider, and encryption of provider ID tokens that Better Auth stores without it. They are not public APIs. A later Better Convex release removes them only after it proves that the new Better Auth version closes both gaps.

Before a production release

Code that compiles proves only that the types match. Before you deploy an application with sensitive data, read the repository security policy, the changelog, and the notes for the exact version that you deploy.