Route Protection

Route protection waits for auth settlement and redirects anonymous users. It protects navigation UX, not Convex data.

Configure defaults

export default defineNuxtConfig({
  modules: ['better-convex-nuxt'],
  convex: {
    auth: {
      routeProtection: {
        redirectTo: '/auth/sign-in',
        preserveReturnTo: true,
      },
    },
  },
})

Protect a page

definePageMeta({
  convexAuth: true,
})

For a page-specific destination:

definePageMeta({
  convexAuth: { redirectTo: '/account/login' },
})

Only local redirect paths are accepted. Protocol-relative paths, backslashes, control characters, and unsafe decoded paths are rejected.

Preserve the return path

With preserveReturnTo: true, the middleware appends a local redirect query value. Validate and normalize that value before navigating after sign-in; never accept an external URL.

Public pages

Pages without convexAuth metadata remain public. An authenticated application can combine public auth: 'none' content and private controls on the same page without protecting the route.

Permission checks

Authentication can be resolved in middleware. Product permissions normally require backend data.

Prefer rendering the protected page and querying a backend capability context unless navigation itself must be denied. Any middleware permission check is still UX; the Convex function repeats the authoritative check.

Caching warning

Do not cache an authenticated SSR page as public HTML. A redirect middleware does not partition a deployment cache by identity.