Registry / database / surreal-better-auth

surreal-better-auth

library1.0.0jsnpmunverified

This package provides an official adapter for integrating SurrealDB with the Better Auth authentication library. It enables `better-auth` to persist user and session data within a SurrealDB instance, leveraging its capabilities for authentication flows. The current stable version is `1.0.0`, with a `2.0.0-beta` series actively under development, indicating a continuous release cadence. A key differentiator is its compliance with `better-auth`'s `createAdapter` utility, ensuring full compatibility with core features like CLI-based schema generation. It also offers advanced ID generation options, including `sdk.UUIDv4` and `sdk.UUIDv7`, providing flexibility in how records are identified within SurrealDB. The library is designed for modern JavaScript/TypeScript environments, requiring Node.js >=20.0.0 or Bun >=1.2.0, and relies on peer dependencies for `surrealdb` and `better-auth`.

database auth-security

npm install surreal-better-auth

github ↗package ↗

INSTALL

IMPORT

SIG · SURREAL-BETTER-AUT

surreal-better-auth

databasejavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

createSurrealDBAdapter

✓ import { createSurrealDBAdapter } from 'surreal-better-auth';

✗ import SurrealDBAdapter from 'surreal-better-auth';

The adapter is exported as a named function, not a default export. Ensure to destructure it correctly.

SurrealDBAdapterOptions

✓ import type { SurrealDBAdapterOptions } from 'surreal-better-auth';

✗ import { SurrealDBAdapterOptions } from 'surreal-better-auth';

This is a TypeScript type; use `import type` for clarity and bundler optimization, though `import` also works.

BetterAuthAdapter

✓ import type { BetterAuthAdapter } from 'better-auth';

While this type comes from 'better-auth', it's crucial for type-checking the adapter's return value.

This quickstart demonstrates how to initialize the `surreal-better-auth` adapter with a SurrealDB instance and integrate it into `better-auth`, configuring it with UUIDv7 for ID generation.

import { createSurrealDBAdapter } from 'surreal-better-auth'; import { BetterAuth } from 'better-auth'; import { Surreal } from 'surrealdb'; async function initializeAuth() { const db = new Surreal('ws://localhost:8000/rpc'); // Ensure you've signed in or created a scope/database for the adapter await db.signin({ user: process.env.SURREAL_USER ?? 'root', pass: process.env.SURREAL_PASS ?? 'root', }); await db.use('test', 'test'); const adapter = createSurrealDBAdapter(db, { idGenerator: 'sdk.UUIDv7', // Use UUIDv7 for better indexing and time-based ordering // You can also define custom ID generation logic here }); const betterAuth = new BetterAuth(adapter); console.log('BetterAuth initialized with SurrealDB adapter.'); // Example: You can now use betterAuth to manage users, sessions, etc. // const newUser = await betterAuth.createUser({ email: 'test@example.com', password: 'password123' }); // console.log('Created user:', newUser); // Cleanup (optional) // await db.close(); } initializeAuth().catch(console.error);

Debug

Known issues

breakingVersion `1.0.0` introduced 'Official Adapter Compliance' by using `better-auth`'s `createAdapter` utility. This might break integrations that relied on older, non-compliant adapter interfaces from pre-1.0 beta versions.

fix

Ensure your adapter implementation or instantiation aligns with the `createAdapter` utility from `better-auth` as shown in the package's documentation. Review your adapter configuration for `idGenerator` options.

affects: >=1.0.0

gotchaThe package currently has an active `2.0.0-beta` release line. While these betas often contain new features like 'bypass ruleset', they might also introduce API changes or instability not present in the stable `1.0.0` release. Always consult the specific beta changelogs.

fix

For production applications, it is generally recommended to stick to the latest stable release (v1.0.0) unless the beta features are critical and their potential for breaking changes is accepted. When using a beta, pin the exact version.

affects: >=2.0.0-beta.1

gotchaThe adapter requires an active SurrealDB connection and appropriate permissions (signin/signup) to perform database operations. Misconfigured permissions or an unauthenticated database connection will lead to failures.

fix

Ensure your SurrealDB instance is running, accessible, and the `db.signin` or `db.signup` calls are correctly executed with sufficient privileges for the database operations the adapter performs (e.g., creating/reading users and sessions).

affects: >=1.0.0

gotchaThe `idGenerator` option, while flexible, needs careful consideration. Using `sdk.UUIDv4` or `sdk.UUIDv7` is recommended for SurrealDB. Custom generators must return unique IDs compatible with SurrealDB's record ID format.

fix

If implementing a custom `idGenerator`, ensure it produces unique and valid SurrealDB record IDs. For most cases, `sdk.UUIDv7` is a good default choice for its ordered nature.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Peer dependency 'surrealdb' not found. Please install it.

The `surrealdb` package is a peer dependency and must be installed separately.

fix

npm install surrealdb

Error: Peer dependency 'better-auth' not found. Please install it.

The `better-auth` package is a peer dependency and must be installed separately.

fix

npm install better-auth

TypeError: Cannot read properties of undefined (reading 'signin') at initializeAuth

The SurrealDB `db` object was not correctly initialized or connected, or the `signin` call failed.

fix

Verify your SurrealDB server is running and accessible at the specified endpoint (e.g., `ws://localhost:8000/rpc`). Check your `db.signin` credentials and ensure they have database access.

Error: Adapter initialization failed: Missing `db` instance.

The `createSurrealDBAdapter` function was called without a valid SurrealDB instance.

fix

Pass an initialized and connected `Surreal` client instance as the first argument to `createSurrealDBAdapter(db, options)`.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

surrealdbrequiredRequired as the underlying database client for SurrealDB operations.

better-authrequiredCore authentication library that this package integrates with.

Agent activity

29 hits · last 30 days

node