PocketBase Better Auth Adapter

1.0.16 verified Sat Apr 25 auth: no javascript

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.

Common errors

error Error: Cannot find module 'pocketbase-better-auth' ↓

cause Package not installed or installed in wrong location (e.g., not in workspace root).

fix

Run npm install pocketbase-better-auth better-auth pocketbase in the project root. Ensure node_modules is not ignored.

error PB_Error: permission denied to perform this action (admin only) ↓

cause The PocketBase admin credentials used are invalid or the admin client is not authenticated.

fix

Verify PB_ADMIN_EMAIL and PB_ADMIN_PASSWORD are correct. Add console.log(pb.authStore.isValid) before adapter init to check auth state.

error Error: Could not find collection 'user' in PocketBase ↓

cause Required collections not imported into PocketBase; or collection names do not match adapter options (singular/plural mismatch).

fix

Import the schema from 'schema/pocketbase.collections.json' into PocketBase admin (Settings > Import collections). Ensure collection names match 'usePlural' setting.

Warnings

breaking Adapter requires PocketBase >=0.20.0; older versions may have incompatible API changes (e.g., filter syntax). ↓

fix Upgrade PocketBase to 0.20.0 or later using `npm install pocketbase@^0.20.0`.

gotcha The adapter uses PocketBase admin API via pb.admins.authWithPassword. Never expose admin credentials client-side; always use server-only environment variables. ↓

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.

gotcha Collection names default to singular (user, session, account, verification). If your PocketBase schema uses plural names, set 'usePlural: true' in adapter options. ↓

fix In adapter config, add `usePlural: true`. Alternatively, import the provided schema (singular) from 'schema/pocketbase.collections.json'.

breaking 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. ↓

fix When importing schema, ensure the 'user' collection is created as a regular collection, not as an Auth collection. See the provided schema file.

gotcha Batch operations (updateMany/deleteMany) are emulated via multiple individual requests. This may cause performance issues on large datasets and is not atomic. ↓

fix Avoid using batch operations with large numbers of records in a single call. Consider batching manually with smaller chunks if needed.

Install

npm install pocketbase-better-auth

yarn add pocketbase-better-auth

pnpm add pocketbase-better-auth

Imports

pocketBaseAdapter
wrong
```
const pocketBaseAdapter = require('pocketbase-better-auth')
```
correct
```
import { pocketBaseAdapter } from 'pocketbase-better-auth'
```
Named export. ESM-only; no CJS support. The adapter factory function for creating the PocketBase adapter instance.
PocketBaseAdapterOptions
wrong
```
import type { PocketBaseAdapterOptions } from 'pocketbase-better-auth'
```
correct
```
import { PocketBaseAdapterOptions } from 'pocketbase-better-auth'
```
TypeScript type. Import using 'import type' for isolatedModules if you only need the type; both forms work for type emission.
default
```
import pocketBaseAdapter from 'pocketbase-better-auth'
```
There is no default export in v1.0.16. Only named export 'pocketBaseAdapter' exists.

Quickstart

Shows minimal setup: create PocketBase client, authenticate as admin, and pass adapter with options to betterAuth.

import { betterAuth } from "better-auth";
import { pocketBaseAdapter } from "pocketbase-better-auth";
import PocketBase from "pocketbase";

const pb = new PocketBase("http://127.0.0.1:8090");
await pb.admins.authWithPassword(
  process.env.PB_ADMIN_EMAIL ?? "admin@example.com",
  process.env.PB_ADMIN_PASSWORD ?? "admin-password"
);

export const auth = betterAuth({
  database: pocketBaseAdapter(pb, {
    usePlural: false,
    debug: false,
  }),
});