Better Auth service

Install compatible packages

Authentication is optional in a minimal app. Choose one setup path from the backend root. Keep existing database tables, patches and overrides when merging these fields.

bun run relkit add auth --adapter better-auth --database-dialect postgresql

{
  "overrides": {
    "@better-fetch/fetch": "1.3.2"
  },
  "pnpm": {
    "overrides": {
      "@better-fetch/fetch": "1.3.2"
    }
  }
}

bun add @relkit/better-auth@0.8.2 @relkit/drizzle@0.8.1 better-auth@1.7.1 drizzle-orm@1.0.0-rc.5-169397b
bun add --dev @cloudflare/workers-types@4.20250121.0 create-relkit@0.8.4 drizzle-kit@1.0.0-rc.5-ab785fc

mkdir -p patches
cp node_modules/create-relkit/dist/patches/drizzle-orm.patch patches/drizzle-orm@1.0.0-rc.5-169397b.patch

{
  "patchedDependencies": {
    "drizzle-orm@1.0.0-rc.5-169397b": "patches/drizzle-orm@1.0.0-rc.5-169397b.patch"
  }
}

bun install

These are owner-specific compatible versions, not a claim about the latest upstream release. The default setup uses Docker PostgreSQL. The service API also supports the existing SQLite example; its database dialect, schema, and migrations must stay consistent. See Database setup.

The backend requires no React package. @relkit/better-auth contains lazy declarations and session types; generated servers select @relkit/better-auth/drizzle for native activation. Applications using the native Effect layers or activateBetterAuthService directly import them from that same /drizzle entrypoint. React belongs to @relkit/better-auth/react and is installed only for a selected React client. Better Auth and Drizzle remain application-owned SDK dependencies; their actual upstream dependencies are retained.

The generated setup includes the Better Fetch declaration override and application-owned Drizzle patch. relkit add auth plans those selected fields automatically; manual consumers must merge them and reinstall. The Cloudflare package above supplies the real D1Database type imported by this SDK’s declarations; it is a development requirement, not a Cloudflare runtime selection. These additions belong only to projects selecting authentication.

Define the service and environment

Create src/services/auth/service.ts:

/** Configures email/password Better Auth against the sole database, borrowing URL and secret from server configuration. */
import { defineBetterAuthService } from "@relkit/better-auth";

export default defineBetterAuthService({
  baseURL: process.env.BETTER_AUTH_URL ?? "http://127.0.0.1:3000",
  // Better Auth reads BETTER_AUTH_SECRET from the server process environment.
  emailAndPassword: { enabled: true },
});

This enables email/password sign-in. The descriptor exposes a stable handler, not a native betterAuth() instance. It does not expose auth.api, an application-owned connection, or a login function to call through context.services.

Add the environment fields to your existing configuration without replacing other settings:

/** Auth and Drizzle share one database; credentials remain in the backend environment. */
import { defineApp, defineEnv, env } from "@relkit/app/config";

export default defineApp({
  env: defineEnv({
    DATABASE_URL: env.secret(),
    BETTER_AUTH_URL: env.url(),
    BETTER_AUTH_SECRET: env.secret(),
  }),
});

Better Auth reads BETTER_AUTH_SECRET from the server process environment when it activates. The example deliberately has no hard-coded secret or secret default. Keep the Docker setup’s DATABASE_URL and the stable auth values in your backend’s untracked .env.local. Generate a secret once if you have not completed the pre-setup:

openssl rand -base64 32

Set BETTER_AUTH_SECRET to that value and BETTER_AUTH_URL to your backend origin, locally http://127.0.0.1:3000. Keep these fields in the existing src/platform/env.ts when the app imports its environment instead of declaring it inline. SQLite apps retain DATABASE_PATH instead of the PostgreSQL DATABASE_URL field.

Store a stable, strong secret in your deployment’s secret manager; use the same value across replicas and restarts. Do not regenerate it on every startup. Never put it in a browser bundle, a public environment variable, source control, logs, or a copied example configuration.

Auth options are a plain object, not an ({ env }) factory. Declaring a field in defineEnv validates the RELKIT environment; it does not inject parsed values into that object or replace process.env. The URL here is read during module evaluation, so supply it before loading the app. The secret uses Better Auth’s native process-environment lookup. A test harness env override alone does not set that process value; see Testing.

Mount the native handler

/** Mounts native Better Auth once for all methods and protects the declared account, order and MCP paths. */
import { defineRoute } from "@relkit/app/routes";
import auth from "@app/services/auth/service.js";

export const ALL = defineRoute({
  handler: auth.handler,
  auth: { protected: ["/account/*", "/orders/*", "/mcp"] },
});

RELKIT derives /api/auth from this route and preserves Better Auth’s native responses, including cookies. The auth.protected paths are application paths that require a session, not endpoints created by Better Auth. See Protect routes for matching and authorization rules.

Do not wrap auth.handler in a function or another handler. Mount the recognized handler directly so the compiler can associate the auth service and its base path. You do not manually call activateBetterAuthService in normal application startup. Calling the descriptor handler before activation returns HTTP 503; importing the descriptor is not a standalone auth server.