Better Auth InstantDB Adapter

Common errors

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

  cause 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'

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

  cause 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, ... })`.

Warnings

• gotcha Email 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.
• breaking InstantDB 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.
• gotcha Incorrect 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.

Install

• npm install better-auth-instantdb npm
• yarn add better-auth-instantdb yarn
• pnpm add better-auth-instantdb pnpm

Imports

• instantAdapter
  wrong:

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

  correct:

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

  Used on the server-side to configure Better Auth with InstantDB.
• useInstantAuth
  wrong:

  import useInstantAuth from 'better-auth-instantdb'

  correct:

  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.

Quickstart

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.');