{"id":18669,"library":"pocketbase-better-auth","title":"PocketBase Better Auth Adapter","description":"A TypeScript-first adapter integrating Better Auth with PocketBase as the authentication backend. Current version 1.0.16 (2024+), actively maintained. It translates Better Auth's CRUD operations into PocketBase collection queries, supporting sessions, accounts, verifications, and batch operations. Key differentiators: PocketBase-native admin API usage, full type safety, customizable table names (singular/plural), and debug logging. Requires PocketBase >=0.20.0 and better-auth >=1.2.6. Tested with 17+ unit tests. No known security incidents.","status":"active","version":"1.0.16","language":"javascript","source_language":"en","source_url":"https://github.com/Lightinn/pocketbase-better-auth","tags":["javascript","typescript","pocketbase","better","better-auth","auth","adapter"],"install":[{"cmd":"npm install pocketbase-better-auth","lang":"bash","label":"npm"},{"cmd":"yarn add pocketbase-better-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add pocketbase-better-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: adapter implements Better Auth's database adapter interface","package":"better-auth","optional":false},{"reason":"Peer dependency: used to connect to PocketBase instance and perform admin API operations","package":"pocketbase","optional":false}],"imports":[{"note":"Named export. ESM-only; no CJS support. The adapter factory function for creating the PocketBase adapter instance.","wrong":"const pocketBaseAdapter = require('pocketbase-better-auth')","symbol":"pocketBaseAdapter","correct":"import { pocketBaseAdapter } from 'pocketbase-better-auth'"},{"note":"TypeScript type. Import using 'import type' for isolatedModules if you only need the type; both forms work for type emission.","wrong":"import type { PocketBaseAdapterOptions } from 'pocketbase-better-auth'","symbol":"PocketBaseAdapterOptions","correct":"import { PocketBaseAdapterOptions } from 'pocketbase-better-auth'"},{"note":"There is no default export in v1.0.16. Only named export 'pocketBaseAdapter' exists.","wrong":"","symbol":"default","correct":"import pocketBaseAdapter from 'pocketbase-better-auth'"}],"quickstart":{"code":"import { betterAuth } from \"better-auth\";\nimport { pocketBaseAdapter } from \"pocketbase-better-auth\";\nimport PocketBase from \"pocketbase\";\n\nconst pb = new PocketBase(\"http://127.0.0.1:8090\");\nawait pb.admins.authWithPassword(\n  process.env.PB_ADMIN_EMAIL ?? \"admin@example.com\",\n  process.env.PB_ADMIN_PASSWORD ?? \"admin-password\"\n);\n\nexport const auth = betterAuth({\n  database: pocketBaseAdapter(pb, {\n    usePlural: false,\n    debug: false,\n  }),\n});","lang":"typescript","description":"Shows minimal setup: create PocketBase client, authenticate as admin, and pass adapter with options to betterAuth."},"warnings":[{"fix":"Upgrade PocketBase to 0.20.0 or later using `npm install pocketbase@^0.20.0`.","message":"Adapter requires PocketBase >=0.20.0; older versions may have incompatible API changes (e.g., filter syntax).","severity":"breaking","affected_versions":"*"},{"fix":"Store PB_ADMIN_EMAIL and PB_ADMIN_PASSWORD in .env file and reference with process.env. Also ensure the PocketBase URL is not exposed to untrusted networks.","message":"The adapter uses PocketBase admin API via pb.admins.authWithPassword. Never expose admin credentials client-side; always use server-only environment variables.","severity":"gotcha","affected_versions":"*"},{"fix":"In adapter config, add `usePlural: true`. Alternatively, import the provided schema (singular) from 'schema/pocketbase.collections.json'.","message":"Collection names default to singular (user, session, account, verification). If your PocketBase schema uses plural names, set 'usePlural: true' in adapter options.","severity":"gotcha","affected_versions":"*"},{"fix":"When importing schema, ensure the 'user' collection is created as a regular collection, not as an Auth collection. See the provided schema file.","message":"Better Auth's default 'users' collection (PocketBase Auth collection) is NOT used. The adapter creates a separate 'user' collection (non-auth). Do not merge with built-in '_superusers' collection.","severity":"breaking","affected_versions":"*"},{"fix":"Avoid using batch operations with large numbers of records in a single call. Consider batching manually with smaller chunks if needed.","message":"Batch operations (updateMany/deleteMany) are emulated via multiple individual requests. This may cause performance issues on large datasets and is not atomic.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run `npm install pocketbase-better-auth better-auth pocketbase` in the project root. Ensure node_modules is not ignored.","cause":"Package not installed or installed in wrong location (e.g., not in workspace root).","error":"Error: Cannot find module 'pocketbase-better-auth'"},{"fix":"Verify PB_ADMIN_EMAIL and PB_ADMIN_PASSWORD are correct. Add `console.log(pb.authStore.isValid)` before adapter init to check auth state.","cause":"The PocketBase admin credentials used are invalid or the admin client is not authenticated.","error":"PB_Error: permission denied to perform this action (admin only)"},{"fix":"Import the schema from 'schema/pocketbase.collections.json' into PocketBase admin (Settings > Import collections). Ensure collection names match 'usePlural' setting.","cause":"Required collections not imported into PocketBase; or collection names do not match adapter options (singular/plural mismatch).","error":"Error: Could not find collection 'user' in PocketBase"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}