Reference

API reference

Every composable, component, utility and hook the module gives your app.

Composables, components and server utilities are auto-imported. The rest come from the package's entries.

Composables

`useAuthActiveOrganization()`

The signed-in user's active organization, server-rendered. It follows the session, so switching organizations updates it. Only with organization on. More

const { organization, activeTeamId, refresh } = useAuthActiveOrganization()
// organization.value: { id, name, slug, logo, members, invitations } | null

`useAuthDeviceAccounts()`

The accounts signed in on this browser, with Better Auth's Multi Session plugin. Empty without it. More

const { accounts, switchTo, signOutOf, addAccountLink, refresh } = useAuthDeviceAccounts()
// accounts.value: Array<{ token, user: { id, name, email, image }, current }>

Switching to an account reloads the app, so every page's data is the new account's.

`useAuthPages()`

Where the module's sign-in and account pages are, as set in pages. A page you turned off is false.

const pages = useAuthPages()
// { signIn: '/login', signUp: '/signup', account: '/account', … }

`useAuthRedirectTarget()`

Where to go after signing in, as @nuxtjs/better-auth decides it: its ?redirect=, else its redirects.authenticated, else /. Only ever a path on your own site.

`useAuthCapabilities()`

What your Better Auth set-up offers: the sign-in methods, providers and plugins that are on. Fetched once per page load, during server rendering.

const { capabilities, loaded } = useAuthCapabilities()
if ((await loaded)?.passkey) {
  // …
}

`useAuthI18n()`

The module's words, in the current language, with your own from messages. More

const { t, locale, errorMessage } = useAuthI18n()
t('signIn.title')
// An error's words: translated by its code when there's a translation, else its own message.
errorMessage(error)

`useBetterAuthAdminCan()`

Whether the signed-in user's role allows these Better Auth Admin permissions, checked with the same roles as the server. Admin dashboard only.

const can = useBetterAuthAdminCan()
can({ user: ['ban'] })

`useBetterAuthAdminPath()`

Turns a path into a URL under the admin route. Admin dashboard only.

const adminPath = useBetterAuthAdminPath()
adminPath('/users') // '/admin/users'

Components

Component
`<AuthAccountSwitcher />`	The accounts signed in on this browser, to switch between, sign out of, or add to. Shows nothing without multi-session. More
`<AuthOrganizationSwitcher />`	The active organization and team, to switch between. Only with `organization` on. More
`<AdminImpersonationBanner />`	"You're signed in as …" while staff impersonate someone, with the way back. Only with the admin dashboard on. More

The module's own pages use components prefixed BetterAuthUi, and composables prefixed useBetterAuthAdmin besides the two above. They're not for your app and may change in any release.

Page meta

betterAuthAdmin adds your own page under the admin route to the dashboard's sidebar and search:

definePageMeta({
  betterAuthAdmin: { label: 'Reports', icon: 'i-lucide-chart-bar', permissions: { user: ['list'] }, order: 0 }
})

Server utilities

Auto-imported in your server routes, with the admin dashboard on. More

`requireBetterAuthAdmin(event, permissions)`

Requires a signed-in user whose role has the Better Auth Admin permissions: a 401 when signed out, a 403 without them. Returns the user, Better Auth's context and its instance.

const { user, context, auth } = await requireBetterAuthAdmin(event, { user: ['list'] })

`recordBetterAuthAdminAction(event, context, entry)`

Adds an entry to the audit log, with the request's IP and browser. Does nothing with the audit log off, and never throws.

await recordBetterAuthAdminAction(event, context, {
  action: 'report.export',
  actor: user,
  // Who it was done to, if anyone.
  target: null,
  details: { rows: 120 }
})

Package entries

For files the module loads, and your Better Auth config.

`@treygrr/nuxt-better-auth-ui/emails`

Export
`defineBetterAuthEmailSender(send)`	Your function that delivers emails, for `emails.send`.
`defineBetterAuthEmail(name, render)`	A template for one email, for `emails.templates`. Returns HTML, or `{ subject, html, text }`.
`betterAuthEmails`	Ready-made callbacks for Better Auth's email options: `verifyEmail`, `resetPassword`, `existingUserSignUp`, `changeEmailConfirmation`, `deleteAccount`.
`renderEmail(name, data, template?, locale?)`	Renders an email as the module would send it: your template, else the default in that language.

`@treygrr/nuxt-better-auth-ui/sms`

Export
`defineBetterAuthSmsSender(send)`	Your function that delivers texts, for `sms.send`. More

`@treygrr/nuxt-better-auth-ui/providers`

Export
`epicGames(options)`, `battleNet(options)`	Generic OAuth configs for providers Better Auth has no helper for.
`placeholderEmail(providerId, accountId)`, `isPlaceholderEmail(email)`	The stand-in address for accounts whose provider shares no email.

Hooks

The module adds Better Auth's plugins itself, so their function options go in files of yours, which it loads:

Option	The file's default export
`emails.send`	Your email sender. More
`emails.templates`	One template per email. More
`sms.send`	Your text sender. More
`anonymous.onLinkAccount`	Better Auth's `onLinkAccount`, to move a guest's data to their new account. More
`organization.serverOptions`	More of the Organization plugin's options, such as `organizationHooks`. More
`sso.serverOptions`	More of the SSO plugin's options, such as `getRole` for who joins as what. More

Better Auth's own hooks (databaseHooks, hooks) go in your Better Auth config, as usual.

How it works

How the module fits into Better Auth and your Nuxt app.

Contributing

Set up the repository, run the playground and tests, and add a feature the way the module does.