Registry / database / better-auth-instantdb

better-auth-instantdb

library1.3.2jsnpmunverified

The Better Auth InstantDB Adapter provides a seamless integration layer, allowing developers to utilize InstantDB as the backing database for Better Auth authentication services. This package, currently at version 1.3.2, facilitates complete authentication flows, automatic session synchronization between Better Auth and InstantDB, and offers type-safe development with TypeScript. While no explicit release cadence is stated, the presence of recent updates (e.g., v1.1.0 addressing email synchronization) suggests active maintenance. Its key differentiators include simplifying the complex task of managing user authentication data by offloading it to InstantDB, providing a customizable setup, and ensuring session consistency across client and server environments. It requires both `@instantdb/admin` for server-side operations and `better-auth` as core peer dependencies.

database auth-security

npm install better-auth-instantdb

package ↗homepage ↗

INSTALL

IMPORT

SIG · BETTER-AUTH-INSTAN

better-auth-instantdb

databasejavascriptv1.3.2

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.

instantAdapter

✓ import { instantAdapter } from 'better-auth-instantdb'

✗ const { instantAdapter } = require('better-auth-instantdb')

Used on the server-side to configure Better Auth with InstantDB.

useInstantAuth

✓ import { useInstantAuth } from 'better-auth-instantdb'

✗ import useInstantAuth from 'better-auth-instantdb'

A client-side React hook for synchronizing authentication state. Ensure it's imported as a named export.

init

✓ import { init } from '@instantdb/admin'

Used to initialize the InstantDB admin client on the server. A separate `init` from `@instantdb/react` is used for the client.

This quickstart demonstrates the basic server-side configuration of Better Auth to use InstantDB as its database, initializing the InstantDB admin client and integrating it via the `instantAdapter`.

import { betterAuth } from "better-auth" import { instantAdapter } from "better-auth-instantdb" import { init } from "@instantdb/admin" // Mock schema and environment variables for demonstration const schema = {}; // In a real app, this would be your InstantDB schema process.env.VITE_INSTANT_APP_ID = process.env.VITE_INSTANT_APP_ID ?? 'your-app-id'; process.env.INSTANT_ADMIN_TOKEN = process.env.INSTANT_ADMIN_TOKEN ?? 'your-admin-token'; // Create InstantDB admin client export const adminDb = init({ schema, appId: process.env.VITE_INSTANT_APP_ID, adminToken: process.env.INSTANT_ADMIN_TOKEN, useDateObjects: true }) // Create Better Auth instance with InstantDB adapter export const auth = betterAuth({ database: instantAdapter({ db: adminDb, usePlural: true, // Optional: set to true if your schema uses plural table names debugLogs: false // Optional: set to true to see detailed logs }), emailAndPassword: { enabled: true }, // ... other Better Auth configuration options }); console.log('Better Auth with InstantDB adapter initialized.');

Debug

Known issues

gotchaEmail synchronization was updated in v1.1.0 to properly sync between 'users' and '$users' tables. While new sign-ins will auto-sync, existing users' emails in the '$users' table will only update on their next sign-in. To batch update historical data, you need to manually run the provided `sync-emails.ts` script.

fix

For existing data, copy the `sync-emails.ts` script (available from the package repository or docs) to your project root and execute it. New sign-ins handle this automatically.

affects: >=1.1.0

breakingInstantDB schema and permissions are critical for security and functionality. The Better Auth CLI can generate a schema, but permissions must be manually configured in `instant.perms.ts`. Failure to correctly define permissions (e.g., for `users`, `accounts`, `sessions`) can lead to security vulnerabilities or prevent authentication flows from working.

fix

Carefully create and review your `instant.perms.ts` file, ensuring `allow` and `bind` rules are correctly defined for all auth-related entities (`users`, `accounts`, `sessions`, `verifications`). Refer to InstantDB documentation for best practices.

affects: >=1.0.0

gotchaIncorrect or missing environment variables (e.g., `VITE_INSTANT_APP_ID`, `INSTANT_ADMIN_TOKEN`, `NEXT_PUBLIC_INSTANT_APP_ID`) will prevent both the server-side InstantDB admin client and the client-side `@instantdb/react` client from initializing correctly, leading to authentication failures.

fix

Ensure all required InstantDB application IDs and admin tokens are correctly set as environment variables, distinguishing between client-side (e.g., `NEXT_PUBLIC_`) and server-side variables.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'appId')

The InstantDB client (admin or react) was initialized without providing the `appId` or it was undefined due to a missing environment variable.

fix

Check that `process.env.VITE_INSTANT_APP_ID` (for server) or `process.env.NEXT_PUBLIC_INSTANT_APP_ID` (for client) are correctly set and accessible in your environment configuration.

InstantDB: Permission denied for operation 'create' on entity 'users'

The InstantDB permissions (in `instant.perms.ts`) do not allow the necessary operations (e.g., 'create', 'update', 'view') for the `users` or other authentication entities.

fix

Review and update your `instant.perms.ts` file. Ensure that roles for `users`, `accounts`, and `sessions` are correctly defined, particularly `bind` and `allow` rules, to permit Better Auth's operations.

Error: `db` is required in instantAdapter options.

The `instantAdapter` was initialized in `betterAuth` without providing an initialized InstantDB admin client.

fix

Ensure `adminDb` (or your variable for the InstantDB admin client) is correctly initialized using `init({ schema, appId, adminToken, ... })` from `@instantdb/admin` and passed to `instantAdapter({ db: adminDb, ... })`.

Upgrade

Version history

1.3.2latest on npm

Audit

Dependencies

@instantdb/adminrequiredRequired for server-side interaction with InstantDB as the authentication database.

better-authrequiredThe core authentication library that this adapter integrates with.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

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

homepagehttps://better-auth.com ↗