surreal-better-auth
Version:
SurrealDB adapter for Better Auth
323 lines (249 loc) • 12.2 kB
Markdown
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/packages/surreal-better-auth/hero.webp?raw=true">
<source media="(prefers-color-scheme: light)" srcset="https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/packages/surreal-better-auth/hero-white.webp?raw=true">
<img alt="surreal-better-auth banner" src="https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/packages/surreal-better-auth/hero.webp?raw=true">
</picture>
</p>
<h1 style="margin-top:40px;"> 🔐 SurrealDB Adapter for Better Auth </h1>
[](https://github.com/sponsors/oskar-gmerek)
**The unofficial [SurrealDB](https://app.surrealdb.com/referral?code=4pn5aba943lpbn8l) adapter for [better-auth](https://better-auth.com)** - bringing the power of the multi-model database to your authentication system.
This adapter seamlessly integrates SurrealDB's advanced querying capabilities with better-auth's comprehensive authentication features, giving you a robust, scalable, and developer-friendly auth solution.
> [!NOTE]
> 🎁 **New to SurrealDB?** [Sign up with our referral link](https://app.surrealdb.com/referral?code=4pn5aba943lpbn8l) and get **free cloud hosting** plus a **special welcome discount** to kickstart your project!
---
## ✨ Features
- 🚀 **Full better-auth compatibility** - Works with all better-auth features and plugins
- 🔄 **Optimized for SurrealDB** - Uses direct record operations for maximum performance
- 🎯 **Smart record links** - Uses record links instead of raw string wherever possible
- 📋 **Schema generation support** - Works with Better Auth CLI, include support for official and unofficial plugins
- 🔍 **Generating Indexes** - Creates necessary database indexes out of the box
- 🆔 **Flexible ID formats** - Supports multiple ID generation strategies, full flexibility
- 🌐 **Multi-format support** - ESM and CommonJS builds included
- ⚡ **Lightweight** - Optimized bundle size
- 📦 **No extra bloat** - This is a pure adapter. It has no direct dependencies and uses the `better-auth` and `surrealdb` you've already installed, giving you full control.
---
## ⭐ Show Your Support
If this adapter helps your project, please consider:
- ⭐ **Starring the project** - It helps others discover this adapter
[](https://github.com/oskar-gmerek/surreal-better-auth)
- 💖 **[Sponsoring the development](https://github.com/sponsors/oskar-gmerek)** - Even small contributions help maintain and improve the project
[](https://github.com/sponsors/oskar-gmerek)
Your support helps us maintain and improve this adapter for the entire community.
---
## 📋 Requirements
- **Node.js**: >= 20.0.0 or **Bun**: >= 1.2.0
- **better-auth**: ^1.3.7
- **surrealdb**: ^1.3.2
---
## 🚀 Installation
```bash
bun add surreal-better-auth
```
```bash
# Using other package managers
npm install surreal-better-auth
yarn add surreal-better-auth
pnpm add surreal-better-auth
```
---
## ⚙️ Configuration
### Adapter Options
| Option | Type | Default | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | --------------------------------------------------- |
| `debugLogs` | `boolean` | `false` | Enable detailed logging for debugging |
| `idGenerator` | `sdk.UUIDv4` \| `sdk.UUIDv7` \| `surreal` \| `surreal.ULID` \| `surreal.UUID` \| `surreal.UUIDv4` \| `surreal.UUIDv7` \| `surreal.guid` \| `undefined` | `undefined` | ID generation strategy (see ID Configuration below) |
| `usePlural` | `boolean` | `false` | Use plural table names (e.g., `users` vs `user`) |
| `allowPassingId` | `boolean` | `false` | Allow passing custom IDs when creating records |
### ID Configuration Options
You can configure ID generation in two ways:
#### 1. Via Adapter Configuration
| `idGenerator` Value | Generated By | Description |
| ------------------- | ------------ | ---------------------------------------------------------------------------- |
| `"sdk.UUIDv4"` | Better Auth | Better Auth generates UUID via SurrealDB JS SDK function `Uuid.v4()` |
| `"sdk.UUIDv7"` | Better Auth | Better Auth generates UUID via SurrealDB JS SDK function `Uuid.v7()` |
| `"surreal"` | Database | SurrealDB generates `default` SurrealDB ID |
| `"surreal.guid"` | Database | SurrealDB generates 20 digit alphanumeric `GUID` |
| `"surreal.ULID"` | Database | SurrealDB generates `ULID` |
| `"surreal.UUID"` | Database | SurrealDB generates default version `UUID` (currently v7) |
| `"surreal.UUIDv4"` | Database | SurrealDB generates `UUID v4` (random-based, most common) |
| `"surreal.UUIDv7"` | Database | SurrealDB generates `UUID v7` (time-based, sortable) |
| `undefined` | Better Auth | Better Auth generates ID (`default`, or generated via `generateId` function) |
#### 2. Via Better-Auth Advanced Configuration
```typescript
// lib/auth.ts
export const auth = betterAuth({
database: surrealAdapter(db, {
idGenerator: "surreal.UUIDv4", // This will be ignored, when generateId is provided!
}),
advanced: {
database: {
generateId() {
return "custom_" + Math.random().toString(36).substr(2, 9);
},
},
},
});
```
### ID Generation Precedence
The ID generation follows this priority order:
1. **`advanced.database.generateId()`** - Highest priority, overrides everything
2. **`idGenerator`** - Used only if `generateId()` is not defined
3. **Custom ID from data** - Used if `allowPassingId` is `true` and ID is provided in the data
4. **Better Auth default** - Used if `allowPassingId` is `true` and ID is NOT provided in the data
5. **Database default ID** - Used as fallback when all above conditions are not met, database generates default ID (same as setting `idGenerator: 'surreal'`)
---
## 🏃♂️ Quick Start
### 1. Set up your SurrealDB connection
```typescript
// lib/db.ts
import Surreal from "surrealdb";
const db = new Surreal();
await db.connect("ws://localhost:8000");
await db.use({ namespace: "production", database: "myapp" });
export { db };
```
### 2. Configure better-auth with the SurrealDB adapter
```typescript
// lib/auth.ts
import { betterAuth } from "better-auth";
import { surrealAdapter } from "surreal-better-auth";
import { db } from "./db";
export const auth = betterAuth({
database: surrealAdapter(db),
emailAndPassword: {
enabled: true,
},
socialProviders: {
github: {
clientId: process.env.GITHUB_CLIENT_ID!,
clientSecret: process.env.GITHUB_CLIENT_SECRET!,
},
},
});
```
### 3. Use in your application
Example for [SvelteKit](https://svelte.dev/)
```typescript
// src/hooks.server.ts
import { auth } from "$lib/auth";
import { svelteKitHandler } from "better-auth/svelte-kit";
import { building } from "$app/environment";
export const handle: Handle = async ({ event, resolve }) => {
return svelteKitHandler({ event, resolve, auth, building });
};
```
```typescript
// src/lib/auth-client.ts
import { createAuthClient } from "better-auth/client";
export const authClient = createAuthClient({
baseURL: "http://localhost:5173", // Your app URL
});
```
```typescript
// src/routes/+page.svelte
<script lang="ts">
import { authClient } from "$lib/client";
const session = authClient.useSession();
</script>
<div>
{#if $session.data}
<div>
<p>
{$session?.data?.user.name}
</p>
<button
onclick={async () => {
await authClient.signOut();
}}
>
Sign Out
</button>
</div>
{:else}
<button
onclick={async () => {
await authClient.signIn.social({
provider: "github",
});
}}
>
Continue with GitHub
</button>
{/if}
</div>
```
---
## 🔧 Advanced Configuration
```typescript
// lib/auth.ts
import { betterAuth } from "better-auth";
import { surrealdbAdapter } from "surreal-better-auth";
import { db } from "./db";
export const auth = betterAuth({
database: surrealdbAdapter(db, {
// Enable debug logging
debugLogs: true,
// Let SurrealDB generate ULID
idGenerator: "surreal.ULID",
// Use singular table names
usePlural: false,
// Allow passing custom IDs
allowPassingId: true,
}),
emailAndPassword: {
enabled: true,
requireEmailVerification: true,
},
socialProviders: {
github: {
clientId: process.env.GITHUB_CLIENT_ID!,
clientSecret: process.env.GITHUB_CLIENT_SECRET!,
},
google: {
clientId: process.env.GOOGLE_CLIENT_ID!,
clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
},
},
plugins: [
// Add any better-auth plugins here and configure them as usual.
],
});
```
## 🧪 Development & Testing
This monorepo includes comprehensive testing to ensure the adapter works reliably:
### Quick Commands
```bash
# Install dependencies
bun install
# Build the adapter
bun run build
# Run adapter unit tests
bun run test:adapter
# Run integration tests (requires SurrealDB)
bun run test:integration
# Run all tests
bun run test:all
# Start example app
bun run dev
```
## 📄 Adapter License
`surreal-better-auth` package - MIT License - see [LICENSE](./packages/surreal-better-auth/LICENSE) for details.
---
## 🔗 Links
- 📖 [better-auth Documentation](https://www.better-auth.com/docs/installation)
- 🗄️ [SurrealDB Documentation](https://surrealdb.com/docs/surrealdb)
- 🌟 [Try SurrealDB Cloud](https://app.surrealdb.com/referral?code=4pn5aba943lpbn8l) (Free tier + welcome bonus!)
- 🐙 [GitHub Repository](https://github.com/oskar-gmerek/surreal-better-auth)
- 📦 [NPM Package](https://www.npmjs.com/package/surreal-better-auth)
---
<div align="center">
**Made with ❤️ for the SurrealDB and Better Auth communities**
[⭐ Star this project](https://github.com/oskar-gmerek/surreal-better-auth) • [🐛 Report Issues](https://github.com/oskar-gmerek/surreal-better-auth/issues) • [💡 Request Features](https://github.com/oskar-gmerek/surreal-better-auth/issues/new)
</div>