@nuxtjs/better-auth

Nuxt module for Better Auth with Nuxt-native route protection, SSR-safe session access, auto-imported helpers, and optional NuxtHub-backed schema generation.

Who this is for

Use this module if you want Better Auth in a Nuxt app and you want the Nuxt-specific pieces handled for you:

• useUserSession() for reactive auth state
• requireUserSession(event) and related server helpers
• route protection through routeRules and definePageMeta({ auth })
• generated server/auth.config.ts and app/auth.config.ts
• optional NuxtHub database integration and schema generation

Requirements

• Nuxt 4.0 or newer
• Node.js ^22.19.0, ^24.11.0, or >=26.0.0
• A Better Auth 1.x version that satisfies this package's peer dependency range
• NuxtHub 0.10.5 or newer when using the optional NuxtHub integration

Install the module

For the fastest path in a Nuxt app:

npx nuxi module add @nuxtjs/better-auth

Then create or confirm these files:

• server/auth.config.ts
• app/auth.config.ts
• .env with NUXT_BETTER_AUTH_SECRET

For the full setup flow, follow the installation guide.

Choose your setup path

• Use NuxtHub integration if you want the shortest path to database-backed auth.
• Use custom database setup if you already have your own database stack.
• Use external auth backend if Better Auth runs in a separate service.
• Use database-less mode for stateless or OAuth-first setups with clear tradeoffs.

Documentation

The documentation site is at better-auth.nuxt.dev.

Recommended reading order:

1. Quickstart
2. Installation
3. Configuration
4. Client setup
5. Route protection

Development

pnpm install
pnpm dev:docs

Useful commands:

• pnpm dev to run the playground
• pnpm dev:docs to run the docs site
• pnpm lint to lint the repo
• pnpm typecheck to check module types
• pnpm prepack to build the publishable package
• pnpm test to run the test suite
• BETTER_AUTH_SECRET=ci-test-secret-12345678901234567890 pnpm dev:build to build the playground with a test secret for local verification only
• pnpm build:docs to build the docs site

See CONTRIBUTING.md for the complete local CI sequence and pull request guidelines.

License

MIT