SurrealDB Adapter for Better Auth

Common errors

• TypeError: surrealAdapter is not a function

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

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

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

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

Warnings

• breaking As 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.
• breaking This 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`.
• gotcha The 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.
• breaking The 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.

Install

• npm install surrealdb-better-auth npm
• yarn add surrealdb-better-auth yarn
• pnpm add surrealdb-better-auth pnpm

Imports

• surrealAdapter
  wrong:

  const surrealAdapter = require('surrealdb-better-auth');

  correct:

  import { surrealAdapter } from 'surrealdb-better-auth';

  The primary named export for initializing the SurrealDB adapter. Designed for ESM environments; CommonJS `require` will not work.
• betterAuth
  wrong:

  import betterAuth from 'better-auth';

  correct:

  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
  wrong:

  import { Adapter } from 'better-auth';

  correct:

  import type { 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.

Quickstart

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");