Release Compatibility

Better Convex Nuxt tests authentication and identity isolation as one dependency tuple. Treat exact peer versions as a security and behavior contract, not package-manager noise.

Current source candidate

The package manifest is the canonical version source. Better Auth and the OAuth Provider are exact optional peers: Convex-only applications install neither, and auth-enabled applications install both explicitly. Better Auth owns its Kysely dependency, so Better Convex does not declare or version a standalone Kysely peer. Stable publication is blocked while the supported Better Auth 1.7 line is still an RC.

Why versions are narrow

Authentication spans Better Auth cookies, its Convex adapter, token exchange, Nuxt request context, SSR serialization, and Convex clients. A semver-compatible-looking upgrade can alter one of those boundaries. The project expands ranges only after its contract, security, browser, and package-artifact checks pass.

Do not use package-manager overrides to silence peer conflicts in production. Upgrade the complete tuple and verify it, or remain on the published tuple.

Upgrade process

There is no migration path into the new integrated auth component. For a fresh application or a later prerelease hard cut:

1. Read every changelog entry between the source and target versions.
2. Install the exact peer versions declared by the target package.
3. Use one fresh betterAuth component; do not attach the new runtime to populated auth data.
4. Regenerate any application-owned local schema and metadata pair, then regenerate Convex types.
5. Run type checks, backend invariants, browser tests, and the clean-tarball application suite.
6. Rehearse sign-in, sign-out, expiry, two-tab logout, account switching, SSR hydration, and reconnect.
7. Verify enabled social OAuth, delegated OAuth, MCP, and recovery ceremonies against real infrastructure.

Pre-1.0 releases can contain deliberate hard cutovers. The project prefers one clear API over compatibility shims; do not keep old and new auth paths side by side.

Tuple-specific security guards

The reviewed auth tuple currently carries two internal, test-covered guards: a URL.canParse primitive for the Convex isolate used by OAuth Provider, and complete encryption coverage for provider ID-token persistence sites omitted by the pinned Better Auth release. They are not public compatibility APIs or dual runtime paths. They may be deleted only when a reviewed replacement tuple proves the upstream gaps are gone; changing versions does not justify removing either guard by inspection alone.

Support evidence

A compiling app proves type compatibility, not operational compatibility. For security-sensitive deployment, review the repository security policy, changelog, and the exact package version you deploy.