|
1 | 1 | <p align="center"> |
2 | 2 | <img src="https://raw.githubusercontent.com/onmax/nuxt-better-auth/main/.github/og.png" alt="Nuxt Better Auth" width="100%"> |
3 | 3 | <br> |
4 | | - <sub>Design inspired by <a href="https://github.com/HugoRCD">HugoRCD</a>'s work</sub> |
| 4 | + <sub>Designed by <a href="https://github.com/HugoRCD">HugoRCD</a></sub> |
5 | 5 | </p> |
6 | 6 |
|
7 | 7 | <h1 align="center">@onmax/nuxt-better-auth</h1> |
8 | 8 |
|
9 | | -<p align="center">Nuxt module for <a href="https://better-auth.com">Better Auth</a> with auto schema generation, route protection, and session management.</p> |
| 9 | +<p align="center">Nuxt module for <a href="https://better-auth.com">Better Auth</a></p> |
10 | 10 |
|
11 | 11 | <p align="center"> |
12 | 12 | <a href="https://npmjs.com/package/@onmax/nuxt-better-auth"><img src="https://img.shields.io/npm/v/@onmax/nuxt-better-auth/latest.svg?style=flat&colorA=020420&colorB=00DC82" alt="npm version"></a> |
|
18 | 18 | > [!WARNING] |
19 | 19 | > This library is a work in progress and not ready for production use. |
20 | 20 |
|
21 | | -Works with [NuxtHub](https://hub.nuxt.com) and future `@nuxt/db`. |
| 21 | +## Documentation |
22 | 22 |
|
23 | | -## Features |
24 | | - |
25 | | -- **Auto Schema Generation** - Generates Drizzle schema from your better-auth plugins |
26 | | -- **Route Protection** - Declarative access rules via `routeRules` |
27 | | -- **Session Management** - SSR-safe session handling with client hydration |
28 | | -- **Role-Based Access** - Support for `admin`, `user`, and custom roles |
29 | | -- **Auto-Imports** - `useUserSession`, `requireUserSession`, `getUserSession` |
30 | | -- **BetterAuthState Component** - Ready-to-use Vue component with slots |
31 | | - |
32 | | -## Requirements |
33 | | - |
34 | | -- NuxtHub with database enabled (`hub: { database: true }`) or future `@nuxt/db` |
35 | | - |
36 | | -## Quick Start |
37 | | - |
38 | | -### 1. Install |
39 | | - |
40 | | -```bash |
41 | | -pnpm add @onmax/nuxt-better-auth better-auth drizzle-orm @nuxthub/core |
42 | | -``` |
43 | | - |
44 | | -### 2. Configure Nuxt |
45 | | - |
46 | | -```ts |
47 | | -export default defineNuxtConfig({ |
48 | | - modules: ['@nuxthub/core', '@onmax/nuxt-better-auth'], |
49 | | - |
50 | | - hub: { database: true }, |
51 | | - |
52 | | - runtimeConfig: { |
53 | | - betterAuthSecret: '', // BETTER_AUTH_SECRET env var |
54 | | - public: { siteUrl: 'http://localhost:3000' }, |
55 | | - }, |
56 | | - |
57 | | - routeRules: { |
58 | | - '/app/**': { auth: 'user' }, |
59 | | - '/admin/**': { auth: { role: 'admin' } }, |
60 | | - '/login': { auth: 'guest' }, |
61 | | - }, |
62 | | -}) |
63 | | -``` |
64 | | - |
65 | | -### 3. Create Server Config |
66 | | - |
67 | | -Create `server/auth.config.ts`: |
68 | | - |
69 | | -```ts |
70 | | -import { admin } from 'better-auth/plugins' |
71 | | -import { defineServerAuth } from '@onmax/nuxt-better-auth' |
72 | | - |
73 | | -export default defineServerAuth(({ db }) => ({ |
74 | | - appName: 'My App', |
75 | | - plugins: [admin()], |
76 | | - emailAndPassword: { enabled: true }, |
77 | | -})) |
78 | | -``` |
79 | | - |
80 | | -> Schema is auto-generated from your plugins! No manual Drizzle schema needed. |
81 | | -
|
82 | | -### 4. Create Client Config |
83 | | - |
84 | | -Create `app/auth.client.ts`: |
85 | | - |
86 | | -```ts |
87 | | -import { adminClient } from 'better-auth/client/plugins' |
88 | | -import { createAuthClient } from 'better-auth/vue' |
89 | | - |
90 | | -export function createAppAuthClient(baseURL: string) { |
91 | | - return createAuthClient({ |
92 | | - baseURL, |
93 | | - plugins: [adminClient()], |
94 | | - }) |
95 | | -} |
96 | | - |
97 | | -export type AppAuthClient = ReturnType<typeof createAppAuthClient> |
98 | | -``` |
99 | | -
|
100 | | -### 5. Add Type Extensions |
101 | | -
|
102 | | -Create `shared/types/auth.d.ts`: |
103 | | -
|
104 | | -```ts |
105 | | -import '#nuxt-better-auth' |
106 | | - |
107 | | -declare module '#nuxt-better-auth' { |
108 | | - interface AuthUser { |
109 | | - role?: string | null |
110 | | - banned?: boolean | null |
111 | | - } |
112 | | -} |
113 | | -``` |
114 | | - |
115 | | -## Route Rules |
116 | | - |
117 | | -| Option | Type | Description | |
118 | | -|--------|------|-------------| |
119 | | -| `auth` | `false \| 'guest' \| 'user' \| { role: string }` | Auth requirement | |
120 | | - |
121 | | -Examples: |
122 | | -- `auth: false` - Public (default) |
123 | | -- `auth: 'guest'` - Only unauthenticated users |
124 | | -- `auth: 'user'` - Any authenticated user |
125 | | -- `auth: { role: 'admin' }` - Requires specific role |
126 | | - |
127 | | -## Composables |
128 | | - |
129 | | -### `useUserSession()` |
130 | | - |
131 | | -```ts |
132 | | -const { user, session, loggedIn, ready, client } = useUserSession() |
133 | | -``` |
134 | | - |
135 | | -### `<BetterAuthState>` |
136 | | - |
137 | | -```vue |
138 | | -<BetterAuthState> |
139 | | - <template #default="{ loggedIn, user, signOut }"> |
140 | | - <p v-if="loggedIn">Welcome, {{ user?.name }}</p> |
141 | | - <p v-else>Not logged in</p> |
142 | | - </template> |
143 | | - <template #placeholder> |
144 | | - <p>Loading...</p> |
145 | | - </template> |
146 | | -</BetterAuthState> |
147 | | -``` |
148 | | - |
149 | | -## Server Utils |
150 | | - |
151 | | -```ts |
152 | | -// Require auth |
153 | | -const { user, session } = await requireUserSession(event) |
154 | | - |
155 | | -// Require admin |
156 | | -const { user } = await requireUserSession(event, { role: 'admin' }) |
157 | | - |
158 | | -// Optional session |
159 | | -const session = await getUserSession(event) |
160 | | -``` |
161 | | - |
162 | | -## Module Aliases |
163 | | - |
164 | | -| Alias | Points To | |
165 | | -|-------|-----------| |
166 | | -| `#auth/server` | `server/auth.config.ts` | |
167 | | -| `#auth/client` | `app/auth.client.ts` | |
168 | | -| `#nuxt-better-auth` | Module type augmentation | |
169 | | - |
170 | | -## Development |
171 | | - |
172 | | -```bash |
173 | | -pnpm install |
174 | | -pnpm dev:prepare |
175 | | -pnpm dev |
176 | | -``` |
| 23 | +**[nuxt-better-auth.onmax.me](https://nuxt-better-auth.onmax.me/)** |
177 | 24 |
|
178 | 25 | ## License |
179 | 26 |
|
|
0 commit comments