Back to Details

nuxt-better-auth

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Nuxt Better Auth

Nuxt Better Auth

Authentication module for Nuxt 4+ built on Better Auth. Provides composables, server utilities, and route protection.
Alpha Status: This module is currently in alpha (v0.0.2-alpha.19) and not recommended for production use. APIs may change.
这是为Nuxt 4+构建的认证模块，基于Better Auth开发。提供组合式函数、服务端工具以及路由保护功能。
Alpha状态：该模块目前处于alpha版本（v0.0.2-alpha.19），不建议用于生产环境。API可能会发生变更。

When to Use

使用场景

  • Installing/configuring 
    @onmax/nuxt-better-auth
  • Implementing login/signup/signout flows
  • Protecting routes (client and server)
  • Accessing user session in API routes
  • Integrating Better Auth plugins (admin, passkey, 2FA)
  • Setting up database with NuxtHub
  • Using clientOnly mode for external auth backends
  • Adding i18n support with 
    @nuxtjs/i18n
For Nuxt patterns: use 
nuxt
skill For NuxtHub database: use 
nuxthub
skill
  • 安装/配置
    @onmax/nuxt-better-auth
  • 实现登录/注册/登出流程
  • 保护路由（客户端和服务端）
  • 在API路由中访问用户会话
  • 集成Better Auth插件（管理后台、密钥登录、双因素认证）
  • 使用NuxtHub设置数据库
  • 为外部认证后端使用clientOnly模式
  • 集成
    @nuxtjs/i18n
    添加国际化支持
关于Nuxt模式：使用
nuxt
技能 关于NuxtHub数据库：使用
nuxthub
技能

Available Guidance

可用指南

FileTopics
references/installation.mdModule setup, env vars, config files
references/client-auth.mduseUserSession, signIn/signUp/signOut, BetterAuthState, safe redirects
references/server-auth.mdserverAuth, getUserSession, requireUserSession
references/route-protection.mdrouteRules, definePageMeta, middleware
references/plugins.mdBetter Auth plugins (admin, passkey, 2FA)
references/database.mdNuxtHub integration, Drizzle schema, custom tables with FKs
references/client-only.mdExternal auth backend, clientOnly mode, CORS
references/types.mdAuthUser, AuthSession, type augmentation
文件主题
references/installation.md模块设置、环境变量、配置文件
references/client-auth.mduseUserSession、signIn/signUp/signOut、BetterAuthState、安全重定向
references/server-auth.mdserverAuth、getUserSession、requireUserSession
references/route-protection.mdrouteRules、definePageMeta、中间件
references/plugins.mdBetter Auth插件（管理后台、密钥登录、双因素认证）
references/database.mdNuxtHub集成、Drizzle schema、带外键的自定义表
references/client-only.md外部认证后端、clientOnly模式、跨域资源共享（CORS）
references/types.mdAuthUser、AuthSession、类型扩展

Loading Files

加载文件

Consider loading these reference files based on your task:
  • references/installation.md - if installing or configuring the module
  • references/client-auth.md - if building login/signup/signout flows
  • references/server-auth.md - if protecting API routes or accessing user session server-side
  • references/route-protection.md - if using routeRules or definePageMeta for auth
  • references/plugins.md - if integrating Better Auth plugins (admin, passkey, 2FA)
  • references/database.md - if setting up database with NuxtHub or Drizzle
  • references/client-only.md - if using external auth backend with clientOnly mode
  • references/types.md - if working with AuthUser, AuthSession, or type augmentation
DO NOT load all files at once. Load only what's relevant to your current task.
请根据你的任务加载相关的参考文件：
  • references/installation.md - 如果正在安装或配置模块
  • references/client-auth.md - 如果正在构建登录/注册/登出流程
  • references/server-auth.md - 如果正在保护API路由或在服务端访问用户会话
  • references/route-protection.md - 如果正在使用routeRules或definePageMeta进行认证
  • references/plugins.md - 如果正在集成Better Auth插件（管理后台、密钥登录、双因素认证）
  • references/database.md - 如果正在使用NuxtHub或Drizzle设置数据库
  • references/client-only.md - 如果正在为外部认证后端使用clientOnly模式
  • references/types.md - 如果正在处理AuthUser、AuthSession或类型扩展
不要一次性加载所有文件。 只加载与当前任务相关的文件。

Key Concepts

核心概念

ConceptDescription
useUserSession()
Client composable - user, session, loggedIn, signIn/Out methods
requireUserSession()
Server helper - throws 401/403 if not authenticated
auth
route mode
'user'
, 
'guest'
, 
{ user: {...} }
, or 
false
serverAuth()
Get Better Auth instance in server routes
概念描述
useUserSession()
客户端组合式函数 - 用户信息、会话、登录状态、signIn/Out方法
requireUserSession()
服务端助手 - 未认证时抛出401/403错误
auth
路由模式
'user'
、
'guest'
、
{ user: {...} }
或
false
serverAuth()
在服务端路由中获取Better Auth实例

Quick Reference

快速参考

ts
// Client: useUserSession()
const { user, loggedIn, signIn, signOut } = useUserSession()
await signIn.email({ email, password }, { onSuccess: () => navigateTo('/') })
ts
// Server: requireUserSession()
const { user } = await requireUserSession(event, { user: { role: 'admin' } })
ts
// nuxt.config.ts: Route protection
routeRules: {
  '/admin/**': { auth: { user: { role: 'admin' } } },
  '/login': { auth: 'guest' },
  '/app/**': { auth: 'user' }
}
ts
// 客户端：useUserSession()
const { user, loggedIn, signIn, signOut } = useUserSession()
await signIn.email({ email, password }, { onSuccess: () => navigateTo('/') })
ts
// 服务端：requireUserSession()
const { user } = await requireUserSession(event, { user: { role: 'admin' } })
ts
// nuxt.config.ts: 路由保护
routeRules: {
  '/admin/**': { auth: { user: { role: 'admin' } } },
  '/login': { auth: 'guest' },
  '/app/**': { auth: 'user' }
}

Resources

资源

Token efficiency: Main skill ~300 tokens, each sub-file ~800-1200 tokens
Token效率：主技能约300个token，每个子文件约800-1200个token