Recipes

User Augmentation

Add custom claims typing to useConvexAuth().user with module augmentation.

Goal

Make useConvexAuth().user understand app-specific claims like role or stripeCustomerId.

Add Module Augmentation

app/types/convex-user.d.ts

declare module 'better-convex-nuxt/dist/runtime/utils/types' {
  interface ConvexUser {
    role?: 'admin' | 'member' | 'viewer'
    stripeCustomerId?: string
    organizationId?: string
  }
}

export {}

Use It in Components

<script setup lang="ts">
const { user } = useConvexAuth()

const isAdmin = computed(() => user.value?.role === 'admin')
</script>

<template>
  <div>
    <p>Customer: {{ user?.stripeCustomerId || 'none' }}</p>
    <p v-if="isAdmin">Admin tools enabled</p>
  </div>
</template>

Best Practice

Treat useConvexAuth().user as UI-friendly identity + claims.
Keep authoritative authorization in Convex queries/mutations (for example via usePermissions() and backend checks).

Real-Time Feed

Build a feed/chat UI with paginated queries and optimistic inserts.

Auth Guards and Permissions

Combine route protection, permissions, and expired-session redirects.