better-auth-studio 1.1.3-beta.5 → 1.1.3-beta.52

package/README.md

@@ -6,6 +6,10 @@
 
 A web-based studio interface for managing Better Auth applications. Better Auth Studio provides a comprehensive dashboard for managing users, organizations, teams, and more.
 
+## Demo Snapshot
+
+![Demo of Better Auth Studio](https://gk6bju9ndq.ufs.sh/f/M5pOhOFFvHQJcwmo00jXSlBtbRHTF15ujAQLPx3VpcKgMOz0)
+
 ## ✨ Try Better Auth Studio Demo
 
 You can try a live, demo version of Better Auth Studio here:
@@ -21,11 +25,11 @@ This online demo lets you explore the admin studio UI. Please note this is a tes
 
 ### Hosted Version
 
-For the hosted version, please join the waitlist: **[better-auth.build](https://better-auth.build)**
+For the hosted version: **[better-auth.build](https://better-auth.build)**
 
 ### Installation
 
-📖 **[Documentation](https://better-auth-studio.vercel.app)**
+📖 **[Documentation](https://better-auth.studio)**
 
 **Recommended: Install as a dev dependency** (for project-specific versions):
 
@@ -77,7 +81,7 @@ Before using Better Auth Studio, ensure you have:
 
 - **Node.js** (v18 or higher)
 - **A Better Auth project** with a valid `auth.ts` configuration file
-- **Database setup** (Prisma, Drizzle, or SQLite)
+- **Database setup** (Prisma, Drizzle, Kysely, or SQLite)
 
 ## 🔧 Configuration
 
@@ -87,9 +91,10 @@ Better Auth Studio automatically detects and works with:
 
 - **Prisma** (`prismaAdapter`)
 - **Drizzle** (`drizzleAdapter`)
+- **Kysely** (`database: { db, type }`)
 - **SQLite** (`new Database()` from better-sqlite3)
-- **PostgreSQL** (via Prisma or Drizzle)
-- **MySQL** (via Prisma or Drizzle)
+- **PostgreSQL** (via Prisma, Drizzle, or Kysely)
+- **MySQL** (via Prisma, Drizzle, or Kysely)
 
 ### Example Configuration Files
 
@@ -127,6 +132,31 @@ export const auth = betterAuth({
 });
 ```
 
+#### Kysely Setup
+
+```typescript
+// auth.ts
+import { betterAuth } from "better-auth";
+import { Kysely, PostgresDialect } from "kysely";
+import { Pool } from "pg";
+
+const db = new Kysely<any>({
+  dialect: new PostgresDialect({
+    pool: new Pool({
+      connectionString: process.env.DATABASE_URL,
+    }),
+  }),
+});
+
+export const auth = betterAuth({
+  database: {
+    db,
+    type: "postgres", // or "mysql", "sqlite", "mssql"
+  },
+  // ... other config
+});
+```
+
 #### SQLite Setup
 
 ```typescript
@@ -154,7 +184,7 @@ export const auth = betterAuth({
 - **Delete users** - Remove users from the system
 - **Bulk operations** - Seed multiple test users
 - **User details** - View user profiles, and accounts
-- **Last seen** - When events are enabled, the studio injects an optional `lastSeenAt` field on the user model and updates it on each sign-in or session creation. Run your database migration (e.g. `prisma migrate dev` or Drizzle push) to add the `lastSeenAt` column to the user table.
+- **Last seen** - When events are enabled, the studio injects an optional `lastSeenAt` field on the user model and updates it on each sign-in or session creation. Run your database migration (e.g. `prisma migrate dev`, Drizzle push, or a Kysely migration) to add the `lastSeenAt` column to the user table.
 
 ### 🏢 Organization Management
 
@@ -183,12 +213,14 @@ pnpx better-auth-studio start [options]
 
 **Options:**
 
-- `--port <number>` - Specify port (default: 3000)
+- `--port <number>` - Specify port (default: 3002)
 - `--host <string>` - Specify host (default: localhost)
 - `--no-open` - Don't automatically open browser
 - `--config <path>` - Path to auth config file (default: auto-detect)
 - `--watch` - Watch for changes in auth config file and reload server automatically
 
+`3002` is just the standalone Studio default so it does not clash with apps that already use `3000`. You can run Studio on `3000`, `4000`, or any other free port.
+
 **Examples:**
 
 ```bash
@@ -266,6 +298,62 @@ pnpm add better-auth-studio
 
 > **Note:** The CLI usage (standalone studio) can be installed as a dev dependency, but self-hosting requires it in `dependencies` for production deployments.
 
+### Docker (Standalone Self-Host)
+
+If you want to run Better Auth Studio in its own container, this repository includes a Docker setup for the standalone CLI server.
+
+This mode is useful when:
+
+- you want a separate admin container
+- your Better Auth app already lives in its own repository
+- you want Docker-managed `node_modules` and package-manager cache volumes
+
+> **Important:** The standalone container still needs your Better Auth project mounted into it, because Studio loads your real `auth.ts` and `studio.config.*` files at runtime.
+
+Build the image from this repository:
+
+```bash
+docker build -t better-auth-studio:self-host .
+```
+
+Run it with Docker Compose:
+
+```bash
+HOST_PROJECT_PATH=/absolute/path/to/your-better-auth-project \
+CONFIG_PATH=./auth.ts \
+docker compose -f docker/compose.yml up --build
+```
+
+If your auth config is not at the project root, pass it explicitly:
+
+```bash
+HOST_PROJECT_PATH=/absolute/path/to/your-better-auth-project \
+CONFIG_PATH=./src/lib/auth.ts \
+docker compose -f docker/compose.yml up --build
+```
+
+If you already used the older filename, `docker/docker-compose.self-host.yml` still works too.
+
+What the container does:
+
+- mounts your Better Auth project into `/workspace`
+- installs project dependencies into Docker volumes on first boot
+- starts `better-auth-studio start --host 0.0.0.0 --port 3002 --no-open`
+
+Useful environment variables:
+
+- `HOST_PROJECT_PATH` - absolute path to your Better Auth project on the host machine
+- `CONFIG_PATH` - optional auth config path inside the mounted project, for example `./src/lib/auth.ts`
+- `PORT` - studio port, defaults to `3002`
+- `WATCH` - set to `true` to enable watch mode
+- `AUTO_INSTALL` - set to `false` if your container/project already has dependencies installed
+- `PROJECT_INSTALL_CMD` - optional custom install command for non-standard setups
+- `GEO_DB_PATH` - optional GeoLite database path inside the mounted project
+
+If you change the Studio port, make sure your Better Auth config also trusts that origin when needed. The examples usually include both `http://localhost:3000` and `http://localhost:3002` for that reason.
+
+If you already embed Studio in your server with the framework adapters below, that remains the recommended production setup. The Docker flow is mainly for running the standalone Studio server in a containerized environment.
+
 ### Setup
 
 **Step 1: Initialize configuration**
@@ -290,6 +378,8 @@ const config: StudioConfig = {
   access: {
     roles: ["admin"],
     allowEmails: ["admin@example.com"],
+    allowIpAddresses: ["127.0.0.1", "::1", "192.168.*"],
+    blockIpAddresses: ["203.0.113.45"],
   },
 };
 
@@ -333,17 +423,56 @@ app.listen(3000);
 
 Access at `http://localhost:3000/api/studio`
 
+### Cloudflare Workers
+
+Use the Worker adapter when the Studio shell needs to run in a non-Node runtime. The adapter avoids Node-only imports, serves UI assets from Workers Assets or an asset map, and delegates Studio API routes to an edge-compatible handler.
+
+```typescript
+import { betterAuthStudio } from "better-auth-studio/cloudflare-workers";
+import { auth } from "./auth";
+
+type Env = {
+  ASSETS: { fetch(request: Request): Promise<Response> | Response };
+};
+
+const studio = betterAuthStudio<Env>({
+  auth,
+  basePath: "/studio",
+  // Optional when your Worker has the default ASSETS binding.
+  assets: (env) => env.ASSETS,
+  apiHandler: async (request) => {
+    // Handle /api/* Studio routes with edge-compatible code here.
+    return new Response(JSON.stringify({ error: "Not implemented" }), {
+      status: 501,
+      headers: { "Content-Type": "application/json" },
+    });
+  },
+});
+
+export default {
+  fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    return studio(request, env, ctx);
+  },
+};
+```
+
+Access at `https://your-worker.example.com/studio`
+
+The built-in Studio API router still depends on Node-only modules, so Workers deployments should provide `apiHandler` for `/api/*` routes. Better Auth auth routes under `/auth/*` are delegated to `auth.handler` when available.
+
 ### Configuration Options
 
-| Option               | Required | Description                                                                                                                                   |
-| -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `auth`               | Yes      | Your Better Auth instance                                                                                                                     |
-| `basePath`           | Yes      | URL path where studio is mounted                                                                                                              |
-| `access.allowEmails` | No       | Array of admin email addresses                                                                                                                |
-| `access.roles`       | No       | Array of allowed user roles                                                                                                                   |
-| `ipAddress`          | No       | IP geolocation for Events/Sessions: `provider` ("ipinfo" \| "ipapi"), `apiToken`, `baseUrl`, optional `endpoint` (ipinfo: "lite" \| "lookup") |
-| `lastSeenAt`         | No       | Enable last-seen tracking: `{ enabled: true, columnName?: string }`                                                                           |
-| `metadata`           | No       | Custom branding (title, theme)                                                                                                                |
+| Option                    | Required | Description                                                                                                                                   |
+| ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `auth`                    | Yes      | Your Better Auth instance                                                                                                                     |
+| `basePath`                | Yes      | URL path where studio is mounted                                                                                                              |
+| `access.allowEmails`      | No       | Array of admin email addresses                                                                                                                |
+| `access.roles`            | No       | Array of allowed user roles                                                                                                                   |
+| `access.allowIpAddresses` | No       | IP allowlist for Studio requests. Supports exact IPs and wildcard patterns (example: `192.168.*`)                                             |
+| `access.blockIpAddresses` | No       | IP blocklist for Studio requests. Supports exact IPs and wildcard patterns                                                                    |
+| `ipAddress`               | No       | IP geolocation for Events/Sessions: `provider` ("ipinfo" \| "ipapi"), `apiToken`, `baseUrl`, optional `endpoint` (ipinfo: "lite" \| "lookup") |
+| `lastSeenAt`              | No       | Enable last-seen tracking: `{ enabled: true, columnName?: string }`                                                                           |
+| `metadata`                | No       | Custom branding (title, theme)                                                                                                                |
 
 ## 📝 Development
 

package/dist/adapters/astro.d.ts

@@ -19,4 +19,3 @@ import type { StudioConfig } from "../types/handler.js";
 export declare function betterAuthStudio(config: StudioConfig): (ctx: {
     request: Request;
 }) => Promise<Response>;
-//# sourceMappingURL=astro.d.ts.map

package/dist/adapters/astro.js

@@ -93,9 +93,12 @@ async function convertAstroToUniversal(ctx, config) {
     };
 }
 function universalToResponse(res) {
+    const headers = new Headers(res.headers);
+    res.setCookies?.forEach((cookie) => {
+        headers.append("Set-Cookie", cookie);
+    });
     return new Response(res.body, {
         status: res.status,
-        headers: res.headers,
+        headers,
     });
 }
-//# sourceMappingURL=astro.js.map

package/dist/adapters/cloudflare-workers.d.ts

@@ -0,0 +1,101 @@
+type MaybePromise<T> = T | Promise<T>;
+export type CloudflareStudioAsset = string | Uint8Array | ArrayBuffer | Response;
+export type CloudflareStudioAssetMap = Record<string, CloudflareStudioAsset>;
+export type CloudflareStudioAssetBinding = {
+    fetch(request: Request): MaybePromise<Response>;
+};
+export type CloudflareStudioAssetSource<Env = unknown> = CloudflareStudioAssetBinding | CloudflareStudioAssetMap | ((env: Env) => MaybePromise<CloudflareStudioAssetBinding | CloudflareStudioAssetMap | null | undefined>);
+export type CloudflareStudioMetadata = {
+    title?: string;
+    logo?: string;
+    favicon?: string;
+    company?: {
+        name?: string;
+        website?: string;
+        supportEmail?: string;
+    };
+    theme?: "dark" | "light" | "auto";
+    colors?: {
+        primary?: string;
+        secondary?: string;
+        accent?: string;
+    };
+    features?: {
+        users?: boolean;
+        sessions?: boolean;
+        organizations?: boolean;
+        analytics?: boolean;
+        tools?: boolean;
+        security?: boolean;
+    };
+    links?: Array<{
+        label: string;
+        url: string;
+    }>;
+    custom?: Record<string, unknown>;
+};
+export type CloudflareStudioAccessConfig = {
+    roles?: string[];
+    allowEmails?: string[];
+    allowIpAddresses?: string[];
+    blockIpAddresses?: string[];
+    sessionDuration?: number;
+    secret?: string;
+};
+export type CloudflareStudioApiContext<Env = unknown, Ctx = unknown> = {
+    env: Env;
+    ctx: Ctx;
+    path: string;
+    originalPath: string;
+    basePath: string;
+    config: CloudflareStudioConfig<Env, Ctx>;
+};
+export type CloudflareStudioApiHandler<Env = unknown, Ctx = unknown> = (request: Request, context: CloudflareStudioApiContext<Env, Ctx>) => MaybePromise<Response | null | undefined>;
+export type CloudflareStudioIndexContext<Env = unknown, Ctx = unknown> = {
+    env: Env;
+    ctx: Ctx;
+    path: string;
+    config: CloudflareStudioConfig<Env, Ctx>;
+};
+export type CloudflareStudioConfig<Env = unknown, Ctx = unknown> = {
+    auth?: {
+        handler?: (request: Request) => MaybePromise<Response>;
+        [key: string]: unknown;
+    };
+    basePath?: string;
+    access?: CloudflareStudioAccessConfig;
+    metadata?: CloudflareStudioMetadata;
+    lastSeenAt?: {
+        enabled?: boolean;
+        columnName?: string;
+    };
+    tools?: {
+        exclude?: string[];
+    };
+    events?: {
+        enabled?: boolean;
+        liveMarquee?: {
+            enabled?: boolean;
+            pollInterval?: number;
+            speed?: number;
+            pauseOnHover?: boolean;
+            limit?: number;
+            sort?: "asc" | "desc";
+            colors?: Record<string, string>;
+            timeWindow?: Record<string, unknown>;
+        };
+    };
+    assets?: CloudflareStudioAssetSource<Env>;
+    indexHtml?: string | ((context: CloudflareStudioIndexContext<Env, Ctx>) => MaybePromise<string | Response | null | undefined>);
+    apiHandler?: CloudflareStudioApiHandler<Env, Ctx>;
+};
+export type CloudflareStudioFetchHandler<Env = unknown, Ctx = unknown> = (request: Request, env?: Env, ctx?: Ctx) => Promise<Response>;
+/**
+ * Cloudflare Workers adapter for Better Auth Studio.
+ *
+ * This entrypoint avoids Node-only imports at module load time. It can serve Studio
+ * UI assets from a Workers Assets binding or an in-memory asset map and delegates
+ * API routes to an edge-compatible handler supplied by the host app.
+ */
+export declare function betterAuthStudio<Env = unknown, Ctx = unknown>(config: CloudflareStudioConfig<Env, Ctx>): CloudflareStudioFetchHandler<Env, Ctx>;
+export {};