Skip to content

Commit 9bf8513

Browse files
authored
docs(auth): document generated Better Auth tables (#722)
## Summary Documents how to import and use Void's generated Better Auth Drizzle tables. ## Changes - Documented the generated Better Auth tables and their exports. - Added import and user-query examples. - Added a foreign-key reference example. - Explained the TypeScript path alias setup. ## Scope Documentation-only. No logic changes. Closes #677
1 parent 8fe70d1 commit 9bf8513

1 file changed

Lines changed: 61 additions & 0 deletions

File tree

‎docs/guide/auth.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,67 @@ import { getSession, getUser, requireAuth } from 'void/auth';
121121

122122
Import `AuthUser` and `AuthSession` from `void/auth` for type annotations. They include the fields your Better Auth plugins and `user.additionalFields` add, such as `role` from `admin()`. See their fields in the [API reference](../reference/api/auth.md#authuser).
123123

124+
## Querying Authentication Tables
125+
126+
When authentication is enabled, Void generates the Better Auth Drizzle schema in `.void/better-auth-schema.ts`.
127+
The generated file exports the core authentication tables:
128+
129+
- `userTable`
130+
- `sessionTable`
131+
- `accountTable`
132+
- `verificationTable`
133+
134+
Configured Better Auth plugins may also contribute additional tables.
135+
136+
The generated file path and core table export names are documented integration points. You can import these exports directly rather than recreating the tables in your application.
137+
138+
To import these tables into your application, add a TypeScript path alias to your root `tsconfig.json`:
139+
140+
```json
141+
{
142+
"compilerOptions": {
143+
"paths": {
144+
"@auth-schema": ["./.void/better-auth-schema.ts"]
145+
}
146+
}
147+
}
148+
```
149+
150+
If your `tsconfig.json` already has a `paths` mapping, add `@auth-schema` to the existing mapping rather than replacing it.
151+
152+
If your project extends `.void/tsconfig.json` and defines its own `paths`, make sure to retain any mappings from the generated configuration that your project uses, such as `@schema`.
153+
154+
You can now import and query authentication tables:
155+
156+
```ts
157+
import { userTable } from '@auth-schema';
158+
import { db, desc } from 'void/db';
159+
160+
export function listUsers() {
161+
return db.select().from(userTable).orderBy(desc(userTable.createdAt));
162+
}
163+
```
164+
165+
You can also reference authentication tables when defining your own Drizzle tables:
166+
167+
```ts
168+
import { userTable } from '@auth-schema';
169+
import { sqliteTable, text } from 'void/schema-d1';
170+
171+
export const postTable = sqliteTable('post', {
172+
id: text('id').primaryKey(),
173+
userId: text('user_id')
174+
.notNull()
175+
.references(() => userTable.id, { onDelete: 'cascade' }),
176+
});
177+
```
178+
179+
This example assumes the default text ID strategy. If you configure `advanced.database.generateId: 'serial'`, use an integer foreign-key column to match the generated user ID.
180+
181+
The example above uses SQLite/D1. For PostgreSQL and MySQL, use the corresponding schema modules: `void/schema-pg` and `void/schema-mysql`.
182+
183+
The generated schema is managed by Void. Do not edit `.void/better-auth-schema.ts` manually, as Void may regenerate it during its build or preparation process.
184+
124185
## Behavior
125186

126187
Auth sessions use the same database as your app. Void creates `BETTER_AUTH_SECRET` on deploy if it is missing and reuses it on later deploys.

0 commit comments

Comments
 (0)