Registry / database / surrealdb-auth-adapter

surrealdb-auth-adapter

library0.2.1jsnpmunverified

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.

database auth-security crm-productivity

npm install surrealdb-auth-adapter

github ↗package ↗

INSTALL

IMPORT

SIG · SURREALDB-AUTH-ADA

surrealdb-auth-adapter

databasejavascriptv0.2.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

surrealdbAdapter

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

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

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

Surreal

✓ import { Surreal } from 'surrealdb'

✗ import Surreal from 'surrealdb'

Surreal is a named export, not default. Using default import will result in undefined.

betterAuth

✓ import { betterAuth } from 'better-auth'

✗ import { BetterAuth } from 'better-auth'

The main function is camelCase named export. Uppercase variants are incorrect.

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; }

Debug

Known issues

breakingIn 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.

affects: 0.2.0

gotchaBetter 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.

affects: >=0.2.0

gotchaThe 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.

affects: >=0.2.0

gotchaPeer 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).

affects: >=0.2.0

deprecatedv0.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.

affects: 0.1.x

Errors

Common errors & fixes

TypeError: dt.getTime is not a function

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 [ERR_MODULE_NOT_FOUND]

Missing peer dependency (better-auth or surrealdb).

fix

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

SyntaxError: Unexpected token 'export'

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).

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

better-authrequiredpeer dependency — core authentication library

surrealdbrequiredpeer dependency — SurrealDB JavaScript SDK (v2)

Agent activity

43 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/cellograph/surrealdb-auth-adapter ↗

packagehttps://www.npmjs.com/package/surrealdb-auth-adapter ↗