Registry / database / surrealdb-better-auth

surrealdb-better-auth

JSON →
library0.0.18jsnpmunverified

The `surrealdb-better-auth` package provides a specialized adapter to seamlessly integrate `SurrealDB` as the data persistence layer for the `Better Auth` authentication library. It enables developers to leverage SurrealDB's flexible, real-time database capabilities for storing user accounts, sessions, and other authentication-related data. As of version 0.0.18, this package is in its early stages of development, indicating a pre-1.0 API stability and a likelihood of frequent updates and potential breaking changes. Its key differentiators include secure authentication, real-time data synchronization with SurrealDB, and a focus on high performance and scalability, all while offering easy configuration within a TypeScript-first environment. It's designed to work with specific peer dependency versions of `better-auth` and `surrealdb`.

npm install surrealdb-better-auth
INSTALL
IMPORT
SIG · SURREALDB-BETTER-A
S
surrealdb-better-auth
databasejavascriptv0.0.18
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

surrealAdapter
import { surrealAdapter } from 'surrealdb-better-auth';
const surrealAdapter = require('surrealdb-better-auth');
The primary named export for initializing the SurrealDB adapter. Designed for ESM environments; CommonJS `require` will not work.
betterAuth
import { betterAuth } from 'better-auth';
import betterAuth from 'better-auth';
While not from `surrealdb-better-auth`, `betterAuth` is the core function from the `better-auth` peer dependency and is essential for using the adapter. It's a named export.
Adapter
import type { Adapter } from 'better-auth';
import { Adapter } from 'better-auth';
To correctly type the adapter function in TypeScript, you might import the `Adapter` interface (or a similar type) from the `better-auth` library itself. Use `import type` for type-only imports.

Demonstrates the basic setup for integrating SurrealDB with Better Auth, configuring the SurrealDB adapter with server address and credentials, using environment variables for sensitive data.

import { betterAuth } from "better-auth"; // Peer dependency, essential for usage import { surrealAdapter } from "surrealdb-better-auth"; // Basic configuration for Better Auth with the SurrealDB adapter export const auth = betterAuth({ secret: process.env.AUTH_SECRET ?? 'super-secret-key-please-change', // A strong secret is crucial for production // ... other Better Auth options as needed database: surrealAdapter({ address: process.env.SURREALDB_ADDRESS ?? "http://localhost:8000", // Your SurrealDB server address username: process.env.SURREALDB_USERNAME ?? "root", // Your SurrealDB username password: process.env.SURREALDB_PASSWORD ?? "root", // Your SurrealDB password ns: process.env.SURREALDB_NAMESPACE ?? "namespace", // Your namespace db: process.env.SURREALDB_DATABASE ?? "database" // Your database name }) }); // Example usage (simplified, assuming 'auth' is exported and used elsewhere) async function authenticateUser(email: string, pass: string) { // In a real application, you'd call 'auth.authenticateUser' or similar methods. console.log(`Attempting to authenticate user: ${email}`); // This quickstart only shows the setup of the adapter, not full auth flow. // For full flow, refer to Better Auth documentation. // Example: const user = await auth.authenticate('credentials', { email, password: pass }); // console.log("User authenticated:", user); console.log("SurrealDB adapter initialized for Better Auth."); return true; // Placeholder for successful initialization } // Call a dummy function to make the quickstart runnable and demonstrate setup authenticateUser("test@example.com", "password123");
Debug
Known issues
breakingAs a pre-1.0 release (version 0.0.18), the API of `surrealdb-better-auth` is not yet stable. Future minor or patch versions may introduce breaking changes without a major version bump, requiring adjustments to your code.
fix
Always pin to exact versions (e.g., `npm install surrealdb-better-auth@0.0.18`) and review changelogs carefully when updating.
affects: <1.0.0
breakingThis package has strict peer dependency requirements for `better-auth` (`^1.2.7 || ^1.4.0`) and `surrealdb` (`1.3.2`). Using incompatible versions of these dependencies can lead to runtime errors or unexpected behavior.
fix
Ensure that your project's installed versions of `better-auth` and `surrealdb` precisely match the peer dependency ranges specified by `surrealdb-better-auth`.
affects: >=0.0.1
gotchaThe default SurrealDB schemas defined by this adapter (Account, Session, User) are `SCHEMALESS`. This provides flexibility but means SurrealDB itself will not enforce data types or structure, leaving validation entirely to the application layer. Inconsistent data might arise if not handled carefully.
fix
Implement robust application-level data validation before writing to SurrealDB, or consider customizing the SurrealDB schema definitions to enforce stricter types and constraints if desired.
affects: >=0.0.1
breakingThe package requires Node.js version 18 or higher (or Bun). Running on older Node.js versions may result in unsupported syntax errors or unexpected failures.
fix
Upgrade your Node.js runtime to version 18 or newer, or use Bun as your JavaScript runtime environment.
affects: <=0.0.18
Errors
Common errors & fixes
TypeError: surrealAdapter is not a function
Attempting to import `surrealAdapter` using CommonJS `require()` syntax or an incorrect named/default import.
fix
Use `import { surrealAdapter } from 'surrealdb-better-auth';` in an ESM-enabled project.
Cannot connect to SurrealDB at http://localhost:8000 (or similar address)
Incorrect SurrealDB connection parameters (address, username, password, namespace, database) or the SurrealDB instance is not running/accessible.
fix
Verify that your SurrealDB server is running and accessible at the specified address, and double-check all connection credentials in your `surrealAdapter` configuration.
Error: Peer dependency 'better-auth@^1.2.7 || ^1.4.0' not installed or mismatched.
The `better-auth` package, a required peer dependency, is either missing from your project or its installed version does not match the range expected by `surrealdb-better-auth`.
fix
Install `better-auth` with a compatible version, e.g., `npm install better-auth@1.4.0` or `pnpm add better-auth@1.4.0`.
Error: The 'database' option must be an instance of an Adapter.
The `surrealAdapter()` function was not correctly called or its return value was not properly passed to the `database` option of `betterAuth()`.
fix
Ensure `betterAuth` is configured as `database: surrealAdapter({...})` and that `surrealAdapter` is called with its required options.
Upgrade
Version history
0.0.18latest on npm
Audit
Dependencies
better-authrequiredCore authentication library for which this package provides a SurrealDB adapter.
surrealdbrequiredThe database client necessary for interacting with a SurrealDB instance.
typescriptoptionalThe package is written in TypeScript and expects a compatible TypeScript version for development and type checking.
Agent activity
30 hits · last 30 days
node
24
Meta
2
OpenAI (training)
1
Resources