Skip to main content

Migration Guide

Upgrade pre-0.6 applications to the current hard-cutover API without compatibility layers.

Version 0.6 replaced the previous auth, query argument, error, permissions, and server-call surfaces. Migrate each use directly; do not keep old and new paths side by side.

Configuration

ts
// Before
convex: {
  auth: {
    enabled: false
  }
}

// Now
convex: {
  auth: false
}

Remove legacy nested auth defaults, automatic auth-mode selection, auth cache options, unauthorized-route recovery, custom auth proxy routes, and the former permissions option. Authentication is installed by default; auth: false is its only off-switch.

Query calls

Every query now receives an explicit arguments object or 'skip'.

ts
useConvexQuery(api.tasks.list, {})

The pre-0.6 omitted-argument form no longer compiles.

Choose one of three auth modes:

  • optional is the default and may run anonymously after auth settles;
  • required waits for an authenticated identity;
  • none always uses a permanently anonymous transport.

Remove legacy public query-key helpers. Import public types from better-convex-nuxt, not the removed /composables subpath.

Authentication client

Define Better Auth client plugins once in convex-auth.ts with defineConvexAuthClient. Remove the pre-0.6 client factory and base-URL helper, plus manual refresh calls after built-in sign-in or sign-up. Those operations now settle Convex identity before returning.

Use app-lifetime state from useConvexAuth() for identity. Reserve .client for plugin-specific methods.

Server calls

Replace all server-specific wrappers with the request-scoped caller:

ts
const convex = await serverConvex(event)
await convex.query(api.tasks.list, {})

Remove the pre-0.6 standalone server query, mutation, and action wrappers and the legacy call composable.

Errors

Handle ConvexCallError for both throwing and safe result paths. Branch on kind, code, or status; do not parse messages or depend on raw upstream response bodies.

Permissions

The package no longer provides a permissions runtime. Keep optional UI capability helpers in your application and enforce every permission in Convex functions. Delete adapters that preserve the removed package API.

Verify the cutover

  1. Search the project for every removed symbol and option.
  2. Typecheck generated Convex API references and Nuxt aliases.
  3. Test anonymous, signed-in, signed-out, and user-switch states.
  4. Test SSR followed by client hydration and realtime updates.
  5. Test authorization with a second tenant or owner.

The complete release history is in the changelog.

Report an issue