@treygrr/nuxt-better-auth-ui

Auth UI for Better Auth in Nuxt, built with Nuxt UI.

Documentation

• Sign-in pages: sign in, sign up, password resets and two-factor, with passkeys, sign-in links, codes by email or text, social and game providers, guests and single sign-on when you turn them on.
• An account page where people manage their profile, email, password, two-factor, passkeys, devices, connected accounts, API keys, billing and data download.
• Organizations: members, invitations, teams, custom roles and SSO providers.
• An admin dashboard at /admin: users, sessions, bans, staff roles, impersonation, an audit log and staff notes, through Better Auth's Admin plugin.
• Auth emails through your own provider, with your own templates.
• English and Spanish, and any word renamed.

Everything is configured under betterAuthUi in nuxt.config.ts. When a feature needs a Better Auth plugin, the module adds it for you.

Quick start

pnpm add @treygrr/nuxt-better-auth-ui @iconify-json/lucide @iconify-json/simple-icons

// nuxt.config.ts
export default defineNuxtConfig({
    modules: ['@treygrr/nuxt-better-auth-ui'],
    betterAuthUi: {
        twoFactor: { enabled: true },
        passkey: { enabled: true }
    }
});

Then point Tailwind at the module's pages, run Better Auth's migrations, and give yourself the admin role: see Installation.

Documentation

Getting started	Installation, and every option at a glance
Sign-in	The pages, the account page, every sign-in method, two-factor, passkeys, security
Organizations	Organizations, roles and permissions, single sign-on
Admin dashboard	Managing users, staff roles, the audit log
Integrations	Stripe, API keys, bearer tokens and JWTs
Customization	Emails, languages and your own words

Development

Contributions are welcome: see Contributing for setting up, the tests, and adding a feature.

pnpm install
cp playground/.env.example playground/.env
pnpm dev:prepare
pnpm dev         # the playground
pnpm test        # builds the module and the playground, starts it once, then runs the API tests and the browser tests
pnpm typecheck
pnpm fmt
pnpm docs:dev      # the documentation site (docs/), on http://localhost:3002
pnpm docs:generate # its static build, as GitHub Pages serves it
pnpm docs:screenshots # retakes the docs' screenshots, from a built playground

The repository is a pnpm workspace: the module at the root, playground/ and docs/ (the documentation site, made with Nuxt Content from the Nuxt UI docs template). Pushes to main that change docs/ publish it to GitHub Pages (.github/workflows/docs.yml).

The browser tests (test/browser/) drive Chromium through the pages: signing up and in, magic links, password resets, the account tabs, two-factor end to end, passkeys with Chromium's virtual authenticator, organizations, single sign-on and the admin. Any console error or warning fails them, so a hydration mismatch does. They use CHROMIUM_PATH, a system Chromium or Chrome, or Playwright's own (npx playwright install chromium); without one they're skipped.

On startup the playground seeds an admin ([email protected] / password123 by default) and 40 mock users from playground/.env: join dates over six months, verified and unverified emails, two more admins, three bans (permanent, expiring, expired), a moderator ([email protected], for trying the playground's moderator role), linked GitHub, Google and Discord accounts (some users have no password), and active sessions on different devices. Mock users share the admin's password. It only adds users that are missing, so delete playground/.data/auth.sqlite to start over.

License

MIT. The parts adapted from the Nuxt UI dashboard template keep its MIT notice; see LICENSE.