Route protection
Redirect anonymous navigation while preserving backend authorization as the security boundary.
Route protection waits until the auth state is known, then redirects anonymous users. It controls navigation only. It does not protect Convex data.
Configure defaults
export default defineNuxtConfig({
modules: ['@lupinum/better-convex-nuxt'],
convex: {
auth: {
origin: process.env.SITE_URL,
redirectTo: '/auth/sign-in',
},
},
})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. An unsafe page-specific redirectTo falls back to convex.auth.redirectTo; the page stays protected.
When auth is temporarily unavailable
The server and the browser use one rule for a failed attempt to learn who is signed in:
| Answer from the auth backend | Meaning | What happens |
|---|---|---|
| No answer, a timeout, 408, 429, or 5xx | Temporary | The session stays, error.code is AUTH_UNAVAILABLE, and the browser retries |
| 401 or 403 | The session is rejected | The session ends, and the middleware redirects |
Any other status, for example a redirect or a 404, or a token without a usable lifetime or sub | Setup error | error.code is AUTH_MISCONFIGURED, and the middleware redirects |
A temporary failure says nothing about the person. The middleware does not redirect then: it renders the protected page with useConvexAuth().status set to 'error' (or still 'pending' while the browser waits out the failure). The browser reads the session again with backoff (2 s, 4 s, up to 60 s) and recovers on its own. Check error.code, not error.message; the message is display text and can change. Show that state instead of a signed-out view:
<script setup lang="ts">
const { error } = useConvexAuth()
</script>
<template>
<p v-if="error?.code === 'AUTH_UNAVAILABLE'">Reconnecting…</p>
<slot v-else />
</template>Convex still refuses data the person may not read, and queries with auth: 'required' stay idle until the identity is known. Any other failure still redirects.
A session-changing call on client, for example client.updateUser(), that meets a temporary failure rejects with AUTH_UNAVAILABLE. The session stays.
Keep signed-in users off guest pages
Mark a sign-in or sign-up page as guest-only:
definePageMeta({
convexAuth: 'guest',
})A signed-out visitor sees the page. A signed-in visitor goes to the validated
redirect query path, or else to convex.auth.guestRedirectTo (default /).
The middleware never redirects to the current page, and it ignores a repeated
redirect parameter.
Preserve the return path
The middleware always appends a validated local redirect query value. After
sign-in, read it with useConvexAuthReturnTo(). It returns the normalized path,
or null when the value is missing, repeated, or unsafe:
const returnTo = useConvexAuthReturnTo()
async function afterSignIn() {
await navigateTo(returnTo.value ?? '/dashboard')
}To validate another value, call normalizeLocalRedirectPath(value). It
accepts any input and returns a safe local path or null. Never navigate to an
external URL from a query parameter.
Public pages
Pages without convexAuth metadata remain public by default. An authenticated application can combine public auth: 'none' content and private controls on the same page without protecting the route.
To protect every page by default, set routes: 'protected':
export default defineNuxtConfig({
convex: {
auth: {
origin: process.env.SITE_URL,
redirectTo: '/auth/sign-in',
routes: 'protected',
},
},
})Then a page without metadata requires sign-in. Opt a public page out with
definePageMeta({ convexAuth: false }). The sign-in page never redirects to
itself.
Permission checks
Authentication can be resolved in middleware. Product permissions normally require backend data.
Prefer to render the page and query the user's permissions from Convex, unless the navigation itself must be blocked. A permission check in middleware only changes what the user sees. The Convex function must repeat the check.
Caching warning
Do not cache an authenticated SSR page as public HTML. A redirect middleware does not split a shared cache by user.