{"id":16912,"library":"surrealdb-better-auth","title":"SurrealDB Adapter for Better Auth","description":"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`.","status":"active","version":"0.0.18","language":"javascript","source_language":"en","source_url":"https://github.com/necmttn/surrealdb-better-auth","tags":["javascript","adapter","auth","authentication","database","better-auth","better-auth-adapter","surrealdb","surrealdb-adapter"],"install":[{"cmd":"npm install surrealdb-better-auth","lang":"bash","label":"npm"},{"cmd":"yarn add surrealdb-better-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add surrealdb-better-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core authentication library for which this package provides a SurrealDB adapter.","package":"better-auth","optional":false},{"reason":"The database client necessary for interacting with a SurrealDB instance.","package":"surrealdb","optional":false},{"reason":"The package is written in TypeScript and expects a compatible TypeScript version for development and type checking.","package":"typescript","optional":true}],"imports":[{"note":"The primary named export for initializing the SurrealDB adapter. Designed for ESM environments; CommonJS `require` will not work.","wrong":"const surrealAdapter = require('surrealdb-better-auth');","symbol":"surrealAdapter","correct":"import { surrealAdapter } from 'surrealdb-better-auth';"},{"note":"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.","wrong":"import betterAuth from 'better-auth';","symbol":"betterAuth","correct":"import { betterAuth } from 'better-auth';"},{"note":"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.","wrong":"import { Adapter } from 'better-auth';","symbol":"Adapter","correct":"import type { Adapter } from 'better-auth';"}],"quickstart":{"code":"import { betterAuth } from \"better-auth\"; // Peer dependency, essential for usage\nimport { surrealAdapter } from \"surrealdb-better-auth\";\n\n// Basic configuration for Better Auth with the SurrealDB adapter\nexport const auth = betterAuth({\n\tsecret: process.env.AUTH_SECRET ?? 'super-secret-key-please-change', // A strong secret is crucial for production\n\t// ... other Better Auth options as needed\n\tdatabase: surrealAdapter({\n\t\taddress: process.env.SURREALDB_ADDRESS ?? \"http://localhost:8000\", // Your SurrealDB server address\n\t\tusername: process.env.SURREALDB_USERNAME ?? \"root\", // Your SurrealDB username\n\t\tpassword: process.env.SURREALDB_PASSWORD ?? \"root\", // Your SurrealDB password\n\t\tns: process.env.SURREALDB_NAMESPACE ?? \"namespace\", // Your namespace\n\t\tdb: process.env.SURREALDB_DATABASE ?? \"database\" // Your database name\n\t})\n});\n\n// Example usage (simplified, assuming 'auth' is exported and used elsewhere)\nasync function authenticateUser(email: string, pass: string) {\n    // In a real application, you'd call 'auth.authenticateUser' or similar methods.\n    console.log(`Attempting to authenticate user: ${email}`);\n    // This quickstart only shows the setup of the adapter, not full auth flow.\n    // For full flow, refer to Better Auth documentation.\n    // Example: const user = await auth.authenticate('credentials', { email, password: pass });\n    // console.log(\"User authenticated:\", user);\n    console.log(\"SurrealDB adapter initialized for Better Auth.\");\n    return true; // Placeholder for successful initialization\n}\n\n// Call a dummy function to make the quickstart runnable and demonstrate setup\nauthenticateUser(\"test@example.com\", \"password123\");","lang":"typescript","description":"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."},"warnings":[{"fix":"Always pin to exact versions (e.g., `npm install surrealdb-better-auth@0.0.18`) and review changelogs carefully when updating.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure that your project's installed versions of `better-auth` and `surrealdb` precisely match the peer dependency ranges specified by `surrealdb-better-auth`.","message":"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.","severity":"breaking","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Upgrade your Node.js runtime to version 18 or newer, or use Bun as your JavaScript runtime environment.","message":"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.","severity":"breaking","affected_versions":"<=0.0.18"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Use `import { surrealAdapter } from 'surrealdb-better-auth';` in an ESM-enabled project.","cause":"Attempting to import `surrealAdapter` using CommonJS `require()` syntax or an incorrect named/default import.","error":"TypeError: surrealAdapter is not a function"},{"fix":"Verify that your SurrealDB server is running and accessible at the specified address, and double-check all connection credentials in your `surrealAdapter` configuration.","cause":"Incorrect SurrealDB connection parameters (address, username, password, namespace, database) or the SurrealDB instance is not running/accessible.","error":"Cannot connect to SurrealDB at http://localhost:8000 (or similar address)"},{"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`.","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`.","error":"Error: Peer dependency 'better-auth@^1.2.7 || ^1.4.0' not installed or mismatched."},{"fix":"Ensure `betterAuth` is configured as `database: surrealAdapter({...})` and that `surrealAdapter` is called with its required options.","cause":"The `surrealAdapter()` function was not correctly called or its return value was not properly passed to the `database` option of `betterAuth()`.","error":"Error: The 'database' option must be an instance of an Adapter."}],"ecosystem":"npm","meta_description":null}