SurrealDB Auth Adapter

0.2.1 verified Fri May 01 auth: no javascript

SurrealDB adapter for Better Auth (v0.2.1) — connects SurrealDB v3 multi-model database to Better Auth's authentication system via the surrealdb@^2.0.3 JS SDK. Integrates with Better Auth CLI to generate SurrealQL schema. Supports multiple ID generation strategies (ULID, UUIDv4, UUIDv7, GUID, auto) either server-side or SDK-side, and accepts both Surreal and SurrealSession instances. Requires Node.js ≥20 or Bun ≥1.2. Key differentiator: native SurrealDB identity generation and datetime handling fixes.

Common errors

error TypeError: dt.getTime is not a function ↓

cause SurrealDB DateTime objects (custom class) are not instances of JS Date, so methods like getTime fail. Happens in JWT plugin when sorting by createdAt.

fix

Update to surrealdb-auth-adapter v0.2.1 which properly converts DateTime to Date.

error Error [ERR_MODULE_NOT_FOUND] ↓

cause Missing peer dependency (better-auth or surrealdb).

fix

Install all required packages: npm install surrealdb-auth-adapter surrealdb better-auth

error SyntaxError: Unexpected token 'export' ↓

cause Attempting to require() an ESM package using CJS require in Node.js without --experimental-require-module.

fix

Use import syntax or enable ESM support (e.g., "type": "module" in package.json).

Warnings

breaking In v0.2.0, SurrealDB DateTime objects were not converted to JS Date, causing JWT plugin crashes when calling .getTime(). Fixed in v0.2.1. ↓

fix Upgrade to v0.2.1 or later. The fix ensures DateTime objects are converted to Date via recordIdsToStrings.

gotcha Better Auth expects plural table names (e.g. 'users'), but SurrealDB defaults to singular. Use `usePlural: true` in adapter options to avoid schema mismatches. ↓

fix Set `usePlural: true` in the adapter configuration or align your SurrealQL schema accordingly.

gotcha The package is ESM-only; using `require()` will fail with a ModuleNotFound error in Node.js <20 or when running without `--experimental-require-module`. ↓

fix Use `import` syntax or ensure Node.js ≥20 with `"type": "module"` in package.json.

gotcha Peer dependencies must be installed explicitly; npm does not auto-install them. Missing better-auth or surrealdb will cause runtime errors. ↓

fix Run `npm install surrealdb-auth-adapter surrealdb better-auth` (or equivalent with bun).

deprecated v0.2.1 is the latest; check for any future breaking changes when upgrading within the 0.x series. ↓

fix Upgrade to v0.2.1. No known breaking changes from 0.2.0 to 0.2.1.

Install

npm install surrealdb-auth-adapter

yarn add surrealdb-auth-adapter

pnpm add surrealdb-auth-adapter

Imports

surrealdbAdapter

wrong

const surrealdbAdapter = require('surrealdb-auth-adapter');

correct

import { surrealdbAdapter } from 'surrealdb-auth-adapter'

Package is ESM-only due to modern dependencies; CJS require will fail.

Surreal
wrong
```
import Surreal from 'surrealdb'
```
correct
```
import { Surreal } from 'surrealdb'
```
Surreal is a named export, not default. Using default import will result in undefined.
betterAuth
wrong
```
import { BetterAuth } from 'better-auth'
```
correct
```
import { betterAuth } from 'better-auth'
```
The main function is camelCase named export. Uppercase variants are incorrect.

Quickstart

Shows how to instantiate Surreal, configure betterAuth with the surrealdbAdapter, and export an auth function for sign-up.

import { Surreal } from 'surrealdb';
import { betterAuth } from 'better-auth';
import { surrealdbAdapter } from 'surrealdb-auth-adapter';

const db = new Surreal();
await db.connect('ws://localhost:8000');
await db.use({ namespace: 'myapp', database: 'production' });

const auth = betterAuth({
  database: surrealdbAdapter(db, {
    idGenerator: 'surreal.ULID',
    usePlural: false,
    debugLogs: false,
  }),
});

export { auth };

export async function signUpUser(email: string, password: string) {
  const user = await auth.api.signUpEmail({
    body: { email, password, name: 'Test' },
  });
  return user;
}