Core Concepts

Sessions

Access reactive session state with SSR support using `useUserSession()`.

pages/dashboard.vue

const {
  user,
  session,
  loggedIn,
  ready,
  signIn,
  signUp,
  signOut,
  fetchSession,
} = useUserSession()

SSR behavior

During server-side rendering (SSR), the module initializes empty session state. When the browser loads the page (hydration), a client plugin fetches the actual session.

Server render: user and session are null, ready is false
After hydration: user and session contain data, ready is true

Use ready or <BetterAuthState> when you need to wait for hydration. Hydration attaches Vue to the server-rendered HTML and makes it interactive.

Database sessions (default): stored in DB, revocable, visible in admin JWE sessions (database-less): encrypted cookie, no server storage

Handling Loading State

pages/protected.vue

<script setup lang="ts">
const { user, loggedIn, ready } = useUserSession()
</script>

<template>
  <div v-if="!ready">Loading...</div>
  <div v-else-if="loggedIn">Welcome, {{ user?.name }}</div>
  <div v-else>Please log in</div>
</template>

Server-Side Session Access

For pages that need session data during SSR without waiting for hydration:

pages/dashboard.vue

<script setup lang="ts">
definePageMeta({ auth: 'user' })
const { user, ready, fetchSession } = useUserSession()

if (import.meta.server) {
  await fetchSession({ headers: useRequestHeaders(['cookie']) })
}
</script>

<template>
  <BetterAuthState>
    <template #default>
      <p v-if="ready">Welcome {{ user?.name }}</p>
    </template>
    <template #placeholder>
      <p>Loading session...</p>
    </template>
  </BetterAuthState>
</template>

Without server-side session initialization, the page briefly shows a loading state before hydration completes.

Session Refresh

Force refresh the session data:

<script setup lang="ts">
const { fetchSession, ready } = useUserSession()
</script>

<template>
  <button :disabled="!ready" @click="fetchSession({ force: true })">
    Refresh session
  </button>
</template>

Session Lifetime

Configure session duration in your auth config:

server/auth.config.ts

import { defineServerAuth } from '@onmax/nuxt-better-auth/config'

export default defineServerAuth({
  session: {
    cookie: {
      maxAge: 60 * 60 * 24 * 7, // 7 days
    },
  },
})