API Reference

Types

Public types and route rule shapes.

import type {
  AppSession,
  AuthActionError,
  AuthMeta,
  AuthMode,
  AuthRouteRules,
  AuthSocialProviderId,
  AuthSession,
  AuthUser,
  RequireSessionOptions,
  UserMatch,
} from '@onmax/nuxt-better-auth'

AuthUser

The user object returned by useUserSession().

string

Unique user identifier.

string

User's email address.

name

string | null

User's display name.

image

string | null

URL to user's avatar image.

emailVerified

boolean

Whether email has been verified.

Additional fields depend on your Better Auth plugins.

AuthSession

The session object returned by useUserSession().

string

Unique session identifier.

userId

string

ID of the user this session belongs to.

expiresAt

Date

When the session expires (database sessions only).

ipAddress

string | null

IP address that created the session.

userAgent

string | null

User agent that created the session.

`AuthMeta`

Used in page meta and route-rule auth entries (routeRules.auth or nitro.routeRules.auth).

pages/dashboard.vue

definePageMeta({ auth: 'user' satisfies AuthMeta })
definePageMeta({ auth: { only: 'guest', redirectTo: '/' } satisfies AuthMeta })

`AuthRouteRules`

Extends Nitro route rules with:

auth?: AuthMeta

nuxt.config.ts

export default defineNuxtConfig({
  routeRules: {
    '/dashboard': { auth: 'user' } satisfies AuthRouteRules,
  },
})

nuxt.config.ts

export default defineNuxtConfig({
  nitro: {
    routeRules: {
      '/dashboard': { auth: 'user' } satisfies AuthRouteRules,
    },
  },
})

`UserMatch<T>`

Used for user matching in AuthMeta.user and RequireSessionOptions.user (OR logic for arrays, AND logic between fields).

`RequireSessionOptions`

The options object for requireUserSession(event, options?). It is augmentation-aware: user matching and rule callback context use AuthUser / AuthSession from #nuxt-better-auth.

`signOut` options

Used by signOut(options?) to run a post-sign-out callback:

await signOut({ onSuccess: () => navigateTo('/') })

`AuthSocialProviderId`

Typed provider ids inferred from your configured socialProviders.

import type { AuthSocialProviderId } from '@onmax/nuxt-better-auth'

const provider: AuthSocialProviderId = 'github'

This replaces verbose extraction patterns like:

type SocialProvider = Parameters<NonNullable<AppAuthClient>['signIn']['social']>[0]['provider']

Module augmentation

Augment AuthUser / AuthSession by declaring module #nuxt-better-auth.

See Type Augmentation for examples.

Using Types

In Vue Components

<script setup lang="ts">
import type { AuthUser } from '#nuxt-better-auth'

const props = defineProps<{
  user: AuthUser
}>()
</script>

In Server Code

server/api/users/[userId].ts

import type { AuthUser, AuthSession } from '#nuxt-better-auth'

export default defineEventHandler(async (event): Promise<AuthUser> => {
  const { user } = await requireUserSession(event)
  return user
})