SpacetimeDB Better Auth Adapter

Use Better Auth with SpacetimeDB in embedded mode, so auth tables live inside the same SpacetimeDB database/module as the rest of your app.

What this package is

• a Better Auth adapter for SpacetimeDB
• an embedded auth table kit for your SpacetimeDB module
• a native path to keep users, sessions, OAuth state, and app data in one database

This package is intentionally embedded-only. It does not publish or manage a separate auth database.

Install

pnpm add better-auth spacetimedb spacetimedb-better-auth

Peer dependencies expected in the consumer app:

• better-auth
• spacetimedb

Quick Start

1. Embed the auth tables in your SpacetimeDB module

import { CaseConversionPolicy, schema } from "spacetimedb/server";
import {
  betterAuthTables,
  registerBetterAuthReducers,
} from "spacetimedb-better-auth/embedded";

const spacetimedb = schema(
  {
    ...betterAuthTables,
    // your app tables...
  },
  {
    CASE_CONVERSION_POLICY: CaseConversionPolicy.None,
  },
);

export default spacetimedb;

export const {
  betterAuthInsertRow,
  betterAuthUpdateRow,
  betterAuthDeleteRow,
} = registerBetterAuthReducers(spacetimedb);

2. Configure Better Auth

import { betterAuth } from "better-auth";
import {
  betterAuthReducerNames,
  spacetimedbAdapter,
} from "spacetimedb-better-auth";

export const auth = betterAuth({
  database: spacetimedbAdapter({
    spacetime: {
      uri: process.env.SPACETIMEDB_HOST!,
      databaseName: process.env.SPACETIMEDB_DB_NAME!,
      token: process.env.SPACETIMEDB_AUTH_TOKEN,
    },
  }),
});

reducers: betterAuthReducerNames is optional because embedded mode is now the default. Keep it only if you want to be explicit or override reducer names.

3. Set your env vars

SPACETIMEDB_HOST=http://localhost:3001
SPACETIMEDB_DB_NAME=your-app-database
SPACETIMEDB_AUTH_TOKEN=

SPACETIMEDB_AUTH_TOKEN is only needed when your SQL API requires authentication.

Maincloud

To test on Maincloud, publish your app module to Maincloud, then point Better Auth and your browser client at that same database.

Typical flow:

spacetime login
cd packages/spacetimedb
spacetime publish --server maincloud your-database-name --module-path spacetimedb --yes
spacetime generate your-database-name --lang typescript --out-dir src/module_bindings --yes

Then configure your deployed app with:

SPACETIMEDB_HOST=https://maincloud.spacetimedb.com
SPACETIMEDB_DB_NAME=your-database-name
NEXT_PUBLIC_SITE_URL=https://your-app-domain.example

Important: your module must accept the Better Auth issuer used by your deployed app. If your app is no longer running on http://localhost:3000, update the issuer allowlist in your SpacetimeDB module before publishing to Maincloud.

The Maincloud dashboard for a database will be under a URL like:

https://spacetimedb.com/@your-account/your-database-name

Configuration

spacetimedbAdapter({
  spacetime: {
    uri: "http://localhost:3001",
    databaseName: "your-dbname-spacetimedb",
    token: "optional-auth-token",
  },
  tablePrefix: "ba_auth_",
  reducers: betterAuthReducerNames,
  debugLogs: false,
  usePlural: false,
});

Options

• spacetime.uri: base HTTP URL for your SpacetimeDB server
• spacetime.databaseName: target app database/module name
• spacetime.token: optional bearer token for the SQL API
• tablePrefix: prefix for Better Auth model tables
• reducers.insert|update|delete: reducer names used for writes
• debugLogs: adapter-level debug logging
• usePlural: pass through to Better Auth adapter factory config

Embedded tables

Core tables:

• ba_auth_user
• ba_auth_session
• ba_auth_account
• ba_auth_verification

Additional bundled support:

• ba_auth_jwks
• ba_auth_oauthClient
• ba_auth_oauthRefreshToken
• ba_auth_oauthAccessToken
• ba_auth_oauthConsent
• ba_auth_app_user_role

Local Development

pnpm install
pnpm test
pnpm build
pnpm release:check

Publishing

This repository is set up for npm Trusted Publishing through GitHub Actions.

Recommended release flow:

npm version patch
git push origin main --follow-tags

When a tag like v0.1.2 is pushed, GitHub Actions will:

• run tests
• build the package
• publish to npm with Trusted Publishing
• create a GitHub Release with generated notes

One-time npm setup:

• open the package settings on npm
• add a Trusted Publisher for hipdev/spacetimedb-better-auth
• point it to .github/workflows/publish.yml

GitHub repository:

• https://github.com/hipdev/spacetimedb-better-auth

Release Notes

This package now targets embedded mode only.

• no companion auth database
• no package CLI
• no separate publish step from the npm package itself

The consumer app owns module publish, module generate, and cloud deployment through standard spacetime commands.