better-auth-devtools 0.1.1-alpha.1 → 0.1.1-alpha.4

package/README.md

@@ -1,14 +1,116 @@
-# better-auth-devtools
+# Better Auth DevTools
 
-An unofficial Better Auth devtool as a single installable package.
+> [!WARNING]
+> Development-only auth tooling. Keep it disabled in production.
 
-This package is currently in alpha and may introduce breaking changes between releases.
+> [!NOTE]
+> This is an alpha release.
 
-This package is unofficial and is not affiliated with, endorsed by, or maintained by the Better Auth team.
+> [!IMPORTANT]
+> This project is unofficial. It is not affiliated with, endorsed by, or maintained by the Better Auth team.
 
-Use subpath exports:
+`better-auth-devtools` is an unofficial Better Auth devtool for local auth scenario testing. It gives you managed test users, instant session switching, session inspection, and a React panel for approved session-field edits.
 
-- `better-auth-devtools/plugin`
-- `better-auth-devtools/react`
+## Installation
 
-See the root README for setup and demo usage.
+```bash
+pnpm add better-auth-devtools
+```
+
+Use these subpath exports:
+
+```ts
+import { devtoolsPlugin, devtoolsClientPlugin } from "better-auth-devtools/plugin";
+import { BetterAuthDevtools } from "better-auth-devtools/react";
+```
+
+Required environment guard:
+
+```bash
+DEV_AUTH_ENABLED=true
+NODE_ENV=development
+```
+
+## AI Agent Prompt
+
+```text
+Install and integrate better-auth-devtools as an unofficial development-only Better Auth utility. Use better-auth-devtools/plugin for the Better Auth server/client plugin setup and better-auth-devtools/react for the floating panel. Keep it disabled in production, require DEV_AUTH_ENABLED=true, use managed test users only, and do not implement arbitrary user impersonation.
+```
+
+## Minimal Usage
+
+```ts
+import { betterAuth } from "better-auth";
+import { createAuthClient } from "better-auth/react";
+import { devtoolsPlugin, devtoolsClientPlugin } from "better-auth-devtools/plugin";
+
+export const auth = betterAuth({
+  database,
+  plugins: [
+    devtoolsPlugin({
+      templates: {
+        admin: { label: "Admin", meta: { role: "admin" } },
+        viewer: { label: "Viewer", meta: { role: "viewer" } },
+      },
+      async createManagedUser(args) {
+        return { userId: "new-user-id", email: args.email, label: args.template.label };
+      },
+      async getSessionView(args) {
+        return {
+          userId: args.userId,
+          fields: { sessionId: args.sessionId, role: "viewer" },
+          editableFields: ["role"],
+        };
+      },
+      async patchSession(args) {
+        return {
+          userId: args.userId,
+          fields: { sessionId: args.sessionId, role: String(args.patch.role ?? "viewer") },
+          editableFields: ["role"],
+        };
+      },
+    }),
+  ],
+});
+
+export const authClient = createAuthClient({
+  plugins: [devtoolsClientPlugin()],
+});
+```
+
+```tsx
+"use client";
+
+import { BetterAuthDevtools } from "better-auth-devtools/react";
+
+export function Devtools() {
+  return (
+    <BetterAuthDevtools
+      enabled={process.env.NODE_ENV !== "production"}
+      basePath="/api/auth"
+      templates={["admin", "viewer"]}
+      editableFields={[
+        { key: "role", label: "Role", type: "select", options: ["admin", "viewer"] },
+      ]}
+    />
+  );
+}
+```
+
+## Demo
+
+```bash
+pnpm install
+pnpm --dir apps/demo-app db:init
+pnpm dev
+```
+
+The demo app in [`apps/demo-app`](https://github.com/C-W-D-Harshit/better-auth-devtools/tree/main/apps/demo-app) is the reference integration.
+
+## Notes
+
+- Managed test users only. This is not arbitrary user impersonation.
+- Intended for local and trusted development environments.
+- Current public API:
+  - `better-auth-devtools/plugin`
+  - `better-auth-devtools/react`

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "better-auth-devtools",
-  "version": "0.1.1-alpha.1",
+  "version": "0.1.1-alpha.4",
   "private": false,
   "description": "Unofficial Better Auth devtool for managed test users, session switching, and a React DevTools panel via plugin/react subpath exports.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "license": "MIT",
   "author": "Harshit",
@@ -37,6 +38,13 @@
       "import": "./dist/react/index.js"
     }
   },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo 'no linter configured'",
+    "test": "pnpm exec vitest run"
+  },
   "keywords": [
     "better-auth",
     "auth",
@@ -57,12 +65,5 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "typescript": "^5.8.0"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit",
-    "lint": "echo 'no linter configured'",
-    "test": "pnpm exec vitest run"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.