Registry / auth-security / pocketbase-better-auth

pocketbase-better-auth

library1.0.16jsnpmunverified

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.

auth-security database web-framework

npm install pocketbase-better-auth

package ↗

INSTALL

IMPORT

SIG · POCKETBASE-BETTER-

pocketbase-better-auth

auth-securityjavascriptv1.0.16

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pocketBaseAdapter

✓ import { pocketBaseAdapter } from 'pocketbase-better-auth'

✗ const pocketBaseAdapter = require('pocketbase-better-auth')

Named export. ESM-only; no CJS support. The adapter factory function for creating the PocketBase adapter instance.

PocketBaseAdapterOptions

✓ import { PocketBaseAdapterOptions } from 'pocketbase-better-auth'

✗ import type { 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.

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, }), });

Debug

Known issues

breakingAdapter 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`.

affects: *

gotchaThe 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.

affects: *

gotchaCollection 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'.

affects: *

breakingBetter 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.

affects: *

gotchaBatch 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.

affects: *

Errors

Common errors & fixes

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

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.

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

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: Could not find collection 'user' in PocketBase

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.

Upgrade

Version history

1.0.16latest on npm

Audit

Dependencies

better-authrequiredPeer dependency: adapter implements Better Auth's database adapter interface

pocketbaserequiredPeer dependency: used to connect to PocketBase instance and perform admin API operations

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/pocketbase-better-auth ↗