{"id":16767,"library":"better-auth-instantdb","title":"Better Auth InstantDB Adapter","description":"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.","status":"active","version":"1.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/daveycodez/better-auth-instantdb","tags":["javascript","typescript","instantdb","better","better-auth","auth","authentication","adapter"],"install":[{"cmd":"npm install better-auth-instantdb","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-instantdb","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-instantdb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for server-side interaction with InstantDB as the authentication database.","package":"@instantdb/admin","optional":false},{"reason":"The core authentication library that this adapter integrates with.","package":"better-auth","optional":false}],"imports":[{"note":"Used on the server-side to configure Better Auth with InstantDB.","wrong":"const { instantAdapter } = require('better-auth-instantdb')","symbol":"instantAdapter","correct":"import { instantAdapter } from 'better-auth-instantdb'"},{"note":"A client-side React hook for synchronizing authentication state. Ensure it's imported as a named export.","wrong":"import useInstantAuth from 'better-auth-instantdb'","symbol":"useInstantAuth","correct":"import { useInstantAuth } from 'better-auth-instantdb'"},{"note":"Used to initialize the InstantDB admin client on the server. A separate `init` from `@instantdb/react` is used for the client.","symbol":"init","correct":"import { init } from '@instantdb/admin'"}],"quickstart":{"code":"import { betterAuth } from \"better-auth\"\nimport { instantAdapter } from \"better-auth-instantdb\"\nimport { init } from \"@instantdb/admin\"\n\n// Mock schema and environment variables for demonstration\nconst schema = {}; // In a real app, this would be your InstantDB schema\nprocess.env.VITE_INSTANT_APP_ID = process.env.VITE_INSTANT_APP_ID ?? 'your-app-id';\nprocess.env.INSTANT_ADMIN_TOKEN = process.env.INSTANT_ADMIN_TOKEN ?? 'your-admin-token';\n\n// Create InstantDB admin client\nexport const adminDb = init({\n  schema,\n  appId: process.env.VITE_INSTANT_APP_ID,\n  adminToken: process.env.INSTANT_ADMIN_TOKEN,\n  useDateObjects: true\n})\n\n// Create Better Auth instance with InstantDB adapter\nexport const auth = betterAuth({\n  database: instantAdapter({\n    db: adminDb,\n    usePlural: true, // Optional: set to true if your schema uses plural table names\n    debugLogs: false  // Optional: set to true to see detailed logs\n  }),\n  emailAndPassword: {\n    enabled: true\n  },\n  // ... other Better Auth configuration options\n});\n\nconsole.log('Better Auth with InstantDB adapter initialized.');","lang":"typescript","description":"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`."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The InstantDB client (admin or react) was initialized without providing the `appId` or it was undefined due to a missing environment variable.","error":"TypeError: Cannot read properties of undefined (reading 'appId')"},{"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.","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.","error":"InstantDB: Permission denied for operation 'create' on entity 'users'"},{"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, ... })`.","cause":"The `instantAdapter` was initialized in `betterAuth` without providing an initialized InstantDB admin client.","error":"Error: `db` is required in instantAdapter options."}],"ecosystem":"npm","meta_description":null}