{"id":26451,"library":"surrealdb-auth-adapter","title":"SurrealDB Auth Adapter","description":"SurrealDB adapter for Better Auth (v0.2.1) — connects SurrealDB v3 multi-model database to Better Auth's authentication system via the surrealdb@^2.0.3 JS SDK. Integrates with Better Auth CLI to generate SurrealQL schema. Supports multiple ID generation strategies (ULID, UUIDv4, UUIDv7, GUID, auto) either server-side or SDK-side, and accepts both Surreal and SurrealSession instances. Requires Node.js ≥20 or Bun ≥1.2. Key differentiator: native SurrealDB identity generation and datetime handling fixes.","status":"active","version":"0.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/cellograph/surrealdb-auth-adapter","tags":["javascript","surrealdb","better-auth","adapter","authentication","database","typescript"],"install":[{"cmd":"npm install surrealdb-auth-adapter","lang":"bash","label":"npm"},{"cmd":"yarn add surrealdb-auth-adapter","lang":"bash","label":"yarn"},{"cmd":"pnpm add surrealdb-auth-adapter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency — core authentication library","package":"better-auth","optional":false},{"reason":"peer dependency — SurrealDB JavaScript SDK (v2)","package":"surrealdb","optional":false}],"imports":[{"note":"Package is ESM-only due to modern dependencies; CJS require will fail.","wrong":"const surrealdbAdapter = require('surrealdb-auth-adapter');","symbol":"surrealdbAdapter","correct":"import { surrealdbAdapter } from 'surrealdb-auth-adapter'"},{"note":"Surreal is a named export, not default. Using default import will result in undefined.","wrong":"import Surreal from 'surrealdb'","symbol":"Surreal","correct":"import { Surreal } from 'surrealdb'"},{"note":"The main function is camelCase named export. Uppercase variants are incorrect.","wrong":"import { BetterAuth } from 'better-auth'","symbol":"betterAuth","correct":"import { betterAuth } from 'better-auth'"}],"quickstart":{"code":"import { Surreal } from 'surrealdb';\nimport { betterAuth } from 'better-auth';\nimport { surrealdbAdapter } from 'surrealdb-auth-adapter';\n\nconst db = new Surreal();\nawait db.connect('ws://localhost:8000');\nawait db.use({ namespace: 'myapp', database: 'production' });\n\nconst auth = betterAuth({\n  database: surrealdbAdapter(db, {\n    idGenerator: 'surreal.ULID',\n    usePlural: false,\n    debugLogs: false,\n  }),\n});\n\nexport { auth };\n\nexport async function signUpUser(email: string, password: string) {\n  const user = await auth.api.signUpEmail({\n    body: { email, password, name: 'Test' },\n  });\n  return user;\n}","lang":"typescript","description":"Shows how to instantiate Surreal, configure betterAuth with the surrealdbAdapter, and export an auth function for sign-up."},"warnings":[{"fix":"Upgrade to v0.2.1 or later. The fix ensures DateTime objects are converted to Date via recordIdsToStrings.","message":"In v0.2.0, SurrealDB DateTime objects were not converted to JS Date, causing JWT plugin crashes when calling .getTime(). Fixed in v0.2.1.","severity":"breaking","affected_versions":"0.2.0"},{"fix":"Set `usePlural: true` in the adapter configuration or align your SurrealQL schema accordingly.","message":"Better Auth expects plural table names (e.g. 'users'), but SurrealDB defaults to singular. Use `usePlural: true` in adapter options to avoid schema mismatches.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Use `import` syntax or ensure Node.js ≥20 with `\"type\": \"module\"` in package.json.","message":"The package is ESM-only; using `require()` will fail with a ModuleNotFound error in Node.js <20 or when running without `--experimental-require-module`.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Run `npm install surrealdb-auth-adapter surrealdb better-auth` (or equivalent with bun).","message":"Peer dependencies must be installed explicitly; npm does not auto-install them. Missing better-auth or surrealdb will cause runtime errors.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Upgrade to v0.2.1. No known breaking changes from 0.2.0 to 0.2.1.","message":"v0.2.1 is the latest; check for any future breaking changes when upgrading within the 0.x series.","severity":"deprecated","affected_versions":"0.1.x"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Update to surrealdb-auth-adapter v0.2.1 which properly converts DateTime to Date.","cause":"SurrealDB DateTime objects (custom class) are not instances of JS Date, so methods like getTime fail. Happens in JWT plugin when sorting by createdAt.","error":"TypeError: dt.getTime is not a function"},{"fix":"Install all required packages: npm install surrealdb-auth-adapter surrealdb better-auth","cause":"Missing peer dependency (better-auth or surrealdb).","error":"Error [ERR_MODULE_NOT_FOUND]"},{"fix":"Use import syntax or enable ESM support (e.g., \"type\": \"module\" in package.json).","cause":"Attempting to require() an ESM package using CJS require in Node.js without --experimental-require-module.","error":"SyntaxError: Unexpected token 'export'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}