{"id":26869385,"url":"https://github.com/oskar-gmerek/surreal-better-auth","last_synced_at":"2026-02-28T04:18:20.187Z","repository":{"id":268611667,"uuid":"904416322","full_name":"oskar-gmerek/surreal-better-auth","owner":"oskar-gmerek","description":"SurrealDB Adapter for Better Auth. Use your favorite database as a Better-Auth storage.","archived":false,"fork":false,"pushed_at":"2025-10-20T23:01:03.000Z","size":340,"stargazers_count":51,"open_issues_count":2,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-22T05:49:31.592Z","etag":null,"topics":["adapter","adapters","auth","authentication","authorization","better-auth","surreal","surrealdb","surrealdb-auth","typescript","typescript-auth"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/surreal-better-auth","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oskar-gmerek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["oskar-gmerek"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2024-12-16T21:06:59.000Z","updated_at":"2025-10-18T13:04:11.000Z","dependencies_parsed_at":"2025-03-31T06:01:39.819Z","dependency_job_id":"5a5f5551-02d4-4119-b867-9d5d7f397529","html_url":"https://github.com/oskar-gmerek/surreal-better-auth","commit_stats":null,"previous_names":["oskar-gmerek/surreal-better-auth"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/oskar-gmerek/surreal-better-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oskar-gmerek%2Fsurreal-better-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oskar-gmerek%2Fsurreal-better-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oskar-gmerek%2Fsurreal-better-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oskar-gmerek%2Fsurreal-better-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oskar-gmerek","download_url":"https://codeload.github.com/oskar-gmerek/surreal-better-auth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oskar-gmerek%2Fsurreal-better-auth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29922071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T19:37:42.220Z","status":"ssl_error","status_checked_at":"2026-02-27T19:37:41.463Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adapter","adapters","auth","authentication","authorization","better-auth","surreal","surrealdb","surrealdb-auth","typescript","typescript-auth"],"created_at":"2025-03-31T06:01:25.499Z","updated_at":"2026-02-28T04:18:20.182Z","avatar_url":"https://github.com/oskar-gmerek.png","language":"TypeScript","funding_links":["https://github.com/sponsors/oskar-gmerek"],"categories":["Adapters"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/packages/surreal-better-auth/hero.webp?raw=true\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/packages/surreal-better-auth/hero-white.webp?raw=true\"\u003e\n    \u003cimg alt=\"surreal-better-auth banner\" src=\"https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/packages/surreal-better-auth/hero.webp?raw=true\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003ch1 style=\"margin-top:40px;\"\u003e 🔐 SurrealDB Adapter for Better Auth \u003c/h1\u003e\n\n![GitHub Created At](https://img.shields.io/github/created-at/oskar-gmerek/surreal-better-auth?style=for-the-badge\u0026color=%233ca916)\n![NPM Last Update](https://img.shields.io/npm/last-update/surreal-better-auth?style=for-the-badge\u0026color=%233ca916)\n![NPM Version](https://img.shields.io/npm/v/surreal-better-auth?style=for-the-badge\u0026color=%233ca916)\n![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/surreal-better-auth?style=for-the-badge\u0026color=%233ca916)\n![NPM Downloads](https://img.shields.io/npm/dy/surreal-better-auth?style=for-the-badge\u0026color=%233ca916)\n![NPM License](https://img.shields.io/npm/l/surreal-better-auth?style=for-the-badge\u0026color=%233ca916)\n[![Sponsor](https://img.shields.io/badge/sponsor-💖-ff69b4?style=for-the-badge\u0026color=%23ffbdbd)](https://github.com/sponsors/oskar-gmerek)\n\n**The unofficial [SurrealDB](https://app.surrealdb.com/referral?code=4pn5aba943lpbn8l) adapter for [better-auth](https://better-auth.com)** - bringing the power of the multi-model database to your authentication system.\n\nThis adapter seamlessly integrates SurrealDB's advanced querying capabilities with better-auth's comprehensive authentication features, giving you a robust, scalable, and developer-friendly auth solution.\n\n\u003e [!NOTE]  \n\u003e  🎁 **New to SurrealDB?** [Sign up with our referral link](https://app.surrealdb.com/referral?code=4pn5aba943lpbn8l) and get **free cloud hosting** plus a **special welcome discount** to kickstart your project!\n\n---\n\n## ✨ Features\n\n- 🚀 **Full better-auth compatibility** - Works with all better-auth features and plugins\n- 🔄 **Optimized for SurrealDB** - Uses direct record operations for maximum performance\n- 🎯 **Smart record links** - Uses record links instead of raw string wherever possible\n- 📋 **Schema generation support** - Works with Better Auth CLI, include support for official and unofficial plugins\n- 🔍 **Generating Indexes** - Creates necessary database indexes out of the box\n- 🆔 **Flexible ID formats** - Supports multiple ID generation strategies, full flexibility\n- 🌐 **Multi-format support** - ESM and CommonJS builds included\n- ⚡ **Lightweight** - Optimized bundle size\n- 📦 **No extra bloat** - This is a pure adapter. It has no direct dependencies and uses the `better-auth` and `surrealdb` you've already installed, giving you full control.\n\n---\n\n## ⭐ Show Your Support\n\nIf this adapter helps your project, please consider:\n\n- ⭐ **Starring the project** - It helps others discover this adapter\n  [![GitHub stars](https://img.shields.io/github/stars/oskar-gmerek/surreal-better-auth?style=social)](https://github.com/oskar-gmerek/surreal-better-auth)\n- 💖 **[Sponsoring the development](https://github.com/sponsors/oskar-gmerek)** - Even small contributions help maintain and improve the project\n  [![Sponsor](https://img.shields.io/badge/sponsor-💖-ff69b4)](https://github.com/sponsors/oskar-gmerek)\n\nYour support helps us maintain and improve this adapter for the entire community.\n\n---\n\n## 📋 Requirements\n\n- **Node.js**: \u003e= 20.0.0 or **Bun**: \u003e= 1.2.0\n- **better-auth**: ^1.3.7\n- **surrealdb**: ^1.3.2\n\n---\n\n## 🚀 Installation\n\n```bash\nbun add surreal-better-auth\n```\n\n```bash\n# Using other package managers\nnpm install surreal-better-auth\nyarn add surreal-better-auth\npnpm add surreal-better-auth\n```\n\n---\n\n## ⚙️ Configuration\n\n### Adapter Options\n\n| Option           | Type                                                                                                                                                   | Default     | Description                                         |\n| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | --------------------------------------------------- |\n| `debugLogs`      | `boolean`                                                                                                                                              | `false`     | Enable detailed logging for debugging               |\n| `idGenerator`    | `sdk.UUIDv4` \\| `sdk.UUIDv7` \\| `surreal` \\| `surreal.ULID` \\| `surreal.UUID` \\| `surreal.UUIDv4` \\| `surreal.UUIDv7` \\| `surreal.guid` \\| `undefined` | `undefined` | ID generation strategy (see ID Configuration below) |\n| `usePlural`      | `boolean`                                                                                                                                              | `false`     | Use plural table names (e.g., `users` vs `user`)    |\n| `allowPassingId` | `boolean`                                                                                                                                              | `false`     | Allow passing custom IDs when creating records      |\n\n### ID Configuration Options\n\nYou can configure ID generation in two ways:\n\n#### 1. Via Adapter Configuration\n\n| `idGenerator` Value | Generated By | Description                                                                  |\n| ------------------- | ------------ | ---------------------------------------------------------------------------- |\n| `\"sdk.UUIDv4\"`      | Better Auth  | Better Auth generates UUID via SurrealDB JS SDK function `Uuid.v4()`         |\n| `\"sdk.UUIDv7\"`      | Better Auth  | Better Auth generates UUID via SurrealDB JS SDK function `Uuid.v7()`         |\n| `\"surreal\"`         | Database     | SurrealDB generates `default` SurrealDB ID                                   |\n| `\"surreal.guid\"`    | Database     | SurrealDB generates 20 digit alphanumeric `GUID`                             |\n| `\"surreal.ULID\"`    | Database     | SurrealDB generates `ULID`                                                   |\n| `\"surreal.UUID\"`    | Database     | SurrealDB generates default version `UUID` (currently v7)                    |\n| `\"surreal.UUIDv4\"`  | Database     | SurrealDB generates `UUID v4` (random-based, most common)                    |\n| `\"surreal.UUIDv7\"`  | Database     | SurrealDB generates `UUID v7` (time-based, sortable)                         |\n| `undefined`         | Better Auth  | Better Auth generates ID (`default`, or generated via `generateId` function) |\n\n#### 2. Via Better-Auth Advanced Configuration\n\n```typescript\n// lib/auth.ts\nexport const auth = betterAuth({\n  database: surrealAdapter(db, {\n    idGenerator: \"surreal.UUIDv4\", // This will be ignored, when generateId is provided!\n  }),\n  advanced: {\n    database: {\n      generateId() {\n        return \"custom_\" + Math.random().toString(36).substr(2, 9);\n      },\n    },\n  },\n});\n```\n\n### ID Generation Precedence\n\nThe ID generation follows this priority order:\n\n1. **`advanced.database.generateId()`** - Highest priority, overrides everything\n2. **`idGenerator`** - Used only if `generateId()` is not defined\n3. **Custom ID from data** - Used if `allowPassingId` is `true` and ID is provided in the data\n4. **Better Auth default** - Used if `allowPassingId` is `true` and ID is NOT provided in the data\n5. **Database default ID** - Used as fallback when all above conditions are not met, database generates default ID (same as setting `idGenerator: 'surreal'`)\n\n---\n\n## 🏃‍♂️ Quick Start\n\n### 1. Set up your SurrealDB connection\n\n```typescript\n// lib/db.ts\nimport Surreal from \"surrealdb\";\n\nconst db = new Surreal();\nawait db.connect(\"ws://localhost:8000\");\nawait db.use({ namespace: \"production\", database: \"myapp\" });\n\nexport { db };\n```\n\n### 2. Configure better-auth with the SurrealDB adapter\n\n```typescript\n// lib/auth.ts\nimport { betterAuth } from \"better-auth\";\nimport { surrealAdapter } from \"surreal-better-auth\";\nimport { db } from \"./db\";\n\nexport const auth = betterAuth({\n  database: surrealAdapter(db),\n  emailAndPassword: {\n    enabled: true,\n  },\n  socialProviders: {\n    github: {\n      clientId: process.env.GITHUB_CLIENT_ID!,\n      clientSecret: process.env.GITHUB_CLIENT_SECRET!,\n    },\n  },\n});\n```\n\n### 3. Use in your application\n\nExample for [SvelteKit](https://svelte.dev/)\n\n```typescript\n// src/hooks.server.ts\nimport { auth } from \"$lib/auth\";\nimport { svelteKitHandler } from \"better-auth/svelte-kit\";\nimport { building } from \"$app/environment\";\n\nexport const handle: Handle = async ({ event, resolve }) =\u003e {\n  return svelteKitHandler({ event, resolve, auth, building });\n};\n```\n\n```typescript\n// src/lib/auth-client.ts\nimport { createAuthClient } from \"better-auth/client\";\n\nexport const authClient = createAuthClient({\n  baseURL: \"http://localhost:5173\", // Your app URL\n});\n```\n\n```typescript\n// src/routes/+page.svelte\n\u003cscript lang=\"ts\"\u003e\n  import { authClient } from \"$lib/client\";\n  const session = authClient.useSession();\n\u003c/script\u003e\n\n    \u003cdiv\u003e\n      {#if $session.data}\n        \u003cdiv\u003e\n          \u003cp\u003e\n            {$session?.data?.user.name}\n          \u003c/p\u003e\n          \u003cbutton\n            onclick={async () =\u003e {\n              await authClient.signOut();\n            }}\n          \u003e\n            Sign Out\n          \u003c/button\u003e\n        \u003c/div\u003e\n      {:else}\n        \u003cbutton\n          onclick={async () =\u003e {\n            await authClient.signIn.social({\n              provider: \"github\",\n            });\n          }}\n        \u003e\n          Continue with GitHub\n        \u003c/button\u003e\n      {/if}\n    \u003c/div\u003e\n```\n\n---\n\n## 🔧 Advanced Configuration\n\n```typescript\n// lib/auth.ts\nimport { betterAuth } from \"better-auth\";\nimport { surrealdbAdapter } from \"surreal-better-auth\";\nimport { db } from \"./db\";\n\nexport const auth = betterAuth({\n  database: surrealdbAdapter(db, {\n    // Enable debug logging\n    debugLogs: true,\n    // Let SurrealDB generate ULID\n    idGenerator: \"surreal.ULID\",\n    // Use singular table names\n    usePlural: false,\n    // Allow passing custom IDs\n    allowPassingId: true,\n  }),\n  emailAndPassword: {\n    enabled: true,\n    requireEmailVerification: true,\n  },\n  socialProviders: {\n    github: {\n      clientId: process.env.GITHUB_CLIENT_ID!,\n      clientSecret: process.env.GITHUB_CLIENT_SECRET!,\n    },\n    google: {\n      clientId: process.env.GOOGLE_CLIENT_ID!,\n      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,\n    },\n  },\n  plugins: [\n    // Add any better-auth plugins here and configure them as usual.\n  ],\n});\n```\n\n## 🧪 Development \u0026 Testing\n\nThis monorepo includes comprehensive testing to ensure the adapter works reliably:\n\n### Quick Commands\n\n```bash\n# Install dependencies\nbun install\n\n# Build the adapter\nbun run build\n\n# Run adapter unit tests\nbun run test:adapter\n\n# Run integration tests (requires SurrealDB)\nbun run test:integration\n\n# Run all tests\nbun run test:all\n\n# Start example app\nbun run dev\n```\n\n## 📄 Adapter License\n\n`surreal-better-auth` package - MIT License - see [LICENSE](./packages/surreal-better-auth/LICENSE) for details.\n\n---\n\n## 🔗 Links\n\n- 📖 [better-auth Documentation](https://www.better-auth.com/docs/installation)\n- 🗄️ [SurrealDB Documentation](https://surrealdb.com/docs/surrealdb)\n- 🌟 [Try SurrealDB Cloud](https://app.surrealdb.com/referral?code=4pn5aba943lpbn8l) (Free tier + welcome bonus!)\n- 🐙 [GitHub Repository](https://github.com/oskar-gmerek/surreal-better-auth)\n- 📦 [NPM Package](https://www.npmjs.com/package/surreal-better-auth)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ for the SurrealDB and Better Auth communities**\n\n[⭐ Star this project](https://github.com/oskar-gmerek/surreal-better-auth) • [🐛 Report Issues](https://github.com/oskar-gmerek/surreal-better-auth/issues) • [💡 Request Features](https://github.com/oskar-gmerek/surreal-better-auth/issues/new)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foskar-gmerek%2Fsurreal-better-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foskar-gmerek%2Fsurreal-better-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foskar-gmerek%2Fsurreal-better-auth/lists"}