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
muslnode 18–226 runs
build_error
glibcnode 18–226 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");
Errors
Common errors & fixes
TypeError: surrealAdapter is not a function
Attempting to import `surrealAdapter` using CommonJS `require()` syntax or an incorrect named/default import.
fixUse `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.
fixVerify 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`.
fixInstall `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()`.
fixEnsure `betterAuth` is configured as `database: surrealAdapter({...})` and that `surrealAdapter` is called with its required options. 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.