Switch users without signing out

Q: What is Better Auth DevTools?

Better Auth DevTools is an open-source npm package, better-auth-devtools, for apps that use Better Auth. It adds a server plugin and a React panel that let you create test users, switch between their sessions, and edit fields such as role during development.

Q: How do I install Better Auth DevTools?

Run pnpm add better-auth-devtools, add devtools({ enabled: true }) to your existing Better Auth config, create the plugin table with a CLI version matching your app, and render once in your React app.

Q: Is it safe to ship the code to production?

Yes. The endpoints are always disabled when NODE_ENV is production, even if enabled is true or DEV_AUTH_ENABLED is set. The panel hides itself when the server reports that DevTools is off.

A dev-only panel in the corner of your app. Create test users, switch to any of them in one click, and change their role on the spot.

pnpm add better-auth-devtools

Setup guide Star on GitHub

localhost:3000/dashboard

Overviewadmin+k3f9@test.local

Signed in as

Adminrole: admin

Publish postsallowed
Invite membersallowed
Manage billingallowed

// GET /api/auth/better-auth-devtools/session
{
  user: { email: "admin+k3f9@test.local", role: "admin" },
  session: { token: "[redacted]" }
}

Auth DevTools

Create test user

Managed users 2

Adminadmin+k3f9@test.localactive
Viewerviewer+p2m1@test.local

Edit session

Role

Interactive preview. Create a user, switch to it, or change its role.

Works with: Better Auth 1.6.11+
Panel: React 18+
License: MIT, free
In production: Always off

Two ways to check the Viewer screen

Without DevTools

Five steps, every time

01Sign out of your own account
02Dig up the password for a test account
03Sign in as that account
04Find your way back to the page
05Repeat for the next role

With DevTools

One click

Pick a template to create a verified test user
Click Switch to get a real Better Auth session
The page reloads as that user
Change the role in place to compare screens

Features

What you can do from the panel

The panel floats in the corner of your app and renders only when the server says DevTools is on.

Create test users
Pick a template, like Admin or Viewer, and the plugin creates a verified Better Auth user for it. You stop borrowing real accounts to test with.
Switch sessions in one click
Click Switch next to any test user. The plugin issues a real Better Auth session for them and reloads the page.
Inspect the current session
See the user and session your app receives. The plugin redacts the session token and anything that looks like a secret before it reaches the browser.
Edit approved fields
Change a role, plan, or flag on the signed-in user. The panel only edits fields you list in editableFields.
Share personas with your team
Templates live in your auth config and get committed with it. Everyone on the team creates the same Admin, Editor, and Viewer users.
Off in production
The endpoints refuse to run when NODE_ENV is production. Development needs an explicit opt-in.

How it works

One server plugin, one React component

The panel calls the plugin's endpoints under your Better Auth base path. The plugin reads and writes through Better Auth's adapter, so it uses the database you already have.

Your React app<BetterAuthDevtools />

fetch /api/auth/*

Better Authdevtools() plugin

adapter

Your databasevia your adapter

Install

Set up in four steps

No client plugin, no props. The panel reads its templates and settings from the server, so the client needs no setup.

Installing with a coding agent? Read the agent guide

Step 1: Install the package
Add it to the app that runs Better Auth. It also needs better-auth, react, and react-dom, which you most likely have already.
pnpm add better-auth-devtools

Step 2: Add the plugin to your auth config

Add the plugin to your existing auth config. Keep its database, user fields, sessions, callbacks, routes, and other plugins. enabled: true opts in during development. Production stays off.

auth.ts (merge these lines)

 import { betterAuth } from "better-auth";
+import { devtools } from "better-auth-devtools";

 export const auth = betterAuth({
   // Keep your existing database, user fields, session options, callbacks, and routes.
-  plugins: [/* existing plugins */],
+  plugins: [/* existing plugins */, devtools({ enabled: true })],
 });

3
Step 3: Create the plugin table
Use a CLI version matching your app's Better Auth version. With the built-in Kysely adapter, run pnpm exec auth migrate. With Prisma or Drizzle, run pnpm exec auth generate, then review and apply your ORM migration. Pass --config if your auth file is elsewhere.
Terminal
```
pnpm exec auth migrate
```
4
Step 4: Mount the panel
Render this client component once in your React tree, such as the root layout. It hides itself when DevTools is off on the server. Start the app, switch to a test user, and check that your app's normal Better Auth session shows that user.
devtools.tsx
```
"use client";

import { BetterAuthDevtools } from "better-auth-devtools/react";

export function Devtools() {
  return <BetterAuthDevtools />;
}
```

Recipe

Testing roles and permissions?

Declare role on the Better Auth user model, then map each template to a role. Add editableFields if you want to change the role of the signed-in user from the panel. If the Better Auth admin plugin already adds role, skip additionalFields.

Advanced hooks and all options

auth.ts

export const auth = betterAuth({
  database,
  user: {
    additionalFields: {
      role: { type: ["admin", "editor", "viewer"], defaultValue: "viewer", input: false },
    },
  },
  plugins: [
    devtools({
      enabled: true,
      templates: {
        admin: { label: "Admin", user: { role: "admin" } },
        editor: { label: "Editor", user: { role: "editor" } },
        viewer: { label: "Viewer", user: { role: "viewer" } },
      },
      editableFields: [
        { key: "role", label: "Role", type: "select", options: ["admin", "editor", "viewer"] },
      ],
    }),
  ],
});

Security

Off unless you turn it on

The plugin creates users and issues real sessions. These checks keep it away from production and away from your real users.

01
Disabled whenever NODE_ENV is production. No option turns it back on.
02
Needs enabled: true or DEV_AUTH_ENABLED=true in development.
03
Only switches to users the plugin created. It can't sign you in as a real user.
04
Write requests need a trusted origin and pass Better Auth's CSRF checks.
05
Allows 60 requests a minute, even when Better Auth's own rate limiter is off.
06
Never sends the raw session token to the browser.

FAQ

Questions and answers

Something missing? Open an issue on GitHub.

Better Auth DevTools is an open-source npm package, better-auth-devtools, for apps that use Better Auth. It adds a server plugin and a React panel that let you create test users, switch between their sessions, and edit fields such as role during development.

Run pnpm add better-auth-devtools, add devtools({ enabled: true }) to your existing Better Auth config, create the plugin table with a CLI version matching your app, and render <BetterAuthDevtools /> once in your React app.

Yes. The endpoints are always disabled when NODE_ENV is production, even if enabled is true or DEV_AUTH_ENABLED is set. The panel hides itself when the server reports that DevTools is off.

Yes. Define templates such as Admin, Editor, and Viewer that set a role on the user, then switch between them from the panel. Add role to editableFields to change it on the signed-in user without creating a new one.

Yes. The plugin goes through Better Auth's own adapter. With the built-in Kysely adapter, run pnpm exec auth migrate. With Prisma, Drizzle, or another ORM, run pnpm exec auth generate and apply the migration with your usual tooling. Match the CLI version to your app's Better Auth version.

Any setup where Better Auth runs on the server and React 18 or newer renders the page, such as Next.js, React Router, TanStack Start, or a Vite app. The panel calls the plugin endpoints under your Better Auth base path, which is /api/auth by default.

No. The panel calls the endpoints directly. The client plugin from better-auth-devtools/plugin is optional and only adds typed actions if your own code needs them.

Better Auth 1.6.11 or newer, below 2.0, React and React DOM 18 or newer, and Node.js 20 or newer. The package is ESM-only.

No. It is an unofficial, community-built tool released under the MIT license. It is not affiliated with the Better Auth team.

Four steps, then you're switching users

Install the package, add the plugin, create its table, and mount the panel.

pnpm add better-auth-devtools

Switch users without signing out

Two ways to check the Viewer screen

Five steps, every time

One click

What you can do from the panel

Create test users

Switch sessions in one click

Inspect the current session

Edit approved fields

Share personas with your team

Off in production

One server plugin, one React component

Set up in four steps

Step 1: Install the package

Step 2: Add the plugin to your auth config

Step 3: Create the plugin table

Step 4: Mount the panel

Testing roles and permissions?

Off unless you turn it on

Questions and answers

What is Better Auth DevTools?

How do I install Better Auth DevTools?

Is it safe to ship the code to production?

Can I test different roles and permissions?

Does it work with Prisma, Drizzle, or other database adapters?

Which frameworks does it support?

Do I need the Better Auth client plugin?

What are the requirements?

Is this an official Better Auth project?

Four steps, then you're switching users