How it works

Better Auth's plugins, added for you

The module registers Better Auth's plugins (the Admin plugin, and those of the features you turn on) through @nuxtjs/better-auth's better-auth:plugins:extend hook, on both the server and the client. Your auth config doesn't change.

The pages then read your Better Auth set-up at runtime, from a public route that says which features are on (never anything about users). That's how they show only what your set-up supports, and pick up plugins your own config adds.

Better Auth does the checking

Everything goes through Better Auth's own endpoints where it has them. Where it doesn't (listing every user's sessions, an admin turning off someone's two-factor), the module adds its own routes under /api/_better-auth-ui, and each checks the same Better Auth permission the matching action needs. Its own tables (the audit log, activity, staff notes) are added through Better Auth's migrations; Better Auth's own tables are never changed.

Admin access

Route rules let only signed-in staff into the admin pages: the admin role, and roles that can list users. Others are sent to the sign-in page or get a 403. Better Auth checks permissions again on every /api/auth/admin/* request.

The pages

• Sign-in and account pages use your app's own layout.
• The admin dashboard uses its own better-auth-ui layout, the dashboard template's sidebar layout, separate from your layouts.
• Components are registered with prefixes (<AuthOrganizationSwitcher> for your app, <BetterAuthUiUserMenu> for the module's own pages), so they can't clash with yours.
• Server-rendered: pages fetch their data on the server and hand it to the browser, so there's no loading flash and no hydration mismatch.

The module also installs @vueuse/nuxt, which the dashboard's pages use. The dashboard template's app.vue, error.vue, colours and CSS theme are left out: they belong to your app.

Composables and components

Serverless hosts

Emails, texts and some audit log entries are sent or written after the response, through Better Auth's background tasks. On serverless hosts, which can stop a function once it has responded, give Better Auth the host's waitUntil:

import { waitUntil } from '@vercel/functions'

export default defineServerAuth({
  advanced: { backgroundTasks: { handler: waitUntil } }
})

For AI agents

The package ships an agent skill in skills/nuxt-better-auth-ui, declared in its package.json. With Nuxt Skill Hub in your app, nuxt prepare installs it for your agent, matching the version you have installed.

Package entries

Everything in them, and the composables, components and server utilities: API reference.