Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BetterAuthDevTools
✓ import { BetterAuthDevTools } from 'better-auth-devtools/client';
✗ const { BetterAuthDevTools } = require('better-auth-devtools/client');
Used for initializing the standalone devtools client. This package is ESM-only; CommonJS `require` is not supported. Ensure correct subpath import for client-specific functionalities.
createBetterAuthDevToolsPlugin
✓ import { createBetterAuthDevToolsPlugin } from 'better-auth-devtools/react';
✗ import createBetterAuthDevToolsPlugin from 'better-auth-devtools/react';
Used to create the plugin for React Developer Tools. It's a named export from the `/react` subpath. Attempting to use a default import will fail.
createBetterAuthDevToolsPlugin
✓ import { createBetterAuthDevToolsPlugin } from 'better-auth-devtools';
✗ const { createBetterAuthDevToolsPlugin } = require('better-auth-devtools');
The root path of the package re-exports `createBetterAuthDevToolsPlugin` for convenience. Prefer the explicit `/react` subpath for clarity, but this works. Still ESM-only.
This quickstart demonstrates how to initialize both the standalone Better Auth DevTools client and integrate the React DevTools plugin into a TypeScript project, providing a foundation for managing authentication states and users during development.
import { BetterAuth } from 'better-auth';
import { BetterAuthDevTools } from 'better-auth-devtools/client';
import { createBetterAuthDevToolsPlugin } from 'better-auth-devtools/react';
// 1. Initialize your BetterAuth instance (replace with your actual configuration)
const betterAuthInstance = new BetterAuth({
baseUrl: process.env.BETTER_AUTH_API_URL ?? 'https://api.example.com/auth',
clientId: process.env.BETTER_AUTH_CLIENT_ID ?? 'your-client-id-here',
// Add other BetterAuth configuration options as needed
});
// 2. Initialize the standalone Better Auth DevTools client
// This provides a separate UI for managing test users and sessions.
BetterAuthDevTools.init({
betterAuthInstance,
config: {
// Example config: enable verbose logging for devtools
debug: true,
// Additional standalone client configuration options can go here
},
});
console.log('Better Auth DevTools standalone client initialized.');
// 3. Create and implicitly register the React DevTools plugin
// This integrates a panel directly into the React Developer Tools extension.
// Simply importing and calling this function in your React app's entry point
// is often enough for the React DevTools extension to pick it up.
const reactDevToolsPlugin = createBetterAuthDevToolsPlugin({
betterAuthInstance,
config: {
// Example config for the React panel: show more details
showSessionDetails: true,
// Additional React plugin configuration options
},
});
console.log('Better Auth DevTools React plugin created and ready for React DevTools.');
// In a typical React application, ensure these initializations happen
// before your main React app renders, often in your 'index.tsx' or 'App.tsx'.
// Example of interacting with betterAuthInstance (for context, not part of devtools init)
async function logUserStatus() {
try {
const user = await betterAuthInstance.getCurrentUser();
if (user) {
console.log('User is logged in:', user.email);
} else {
console.log('No user currently logged in.');
}
} catch (error) {
console.error('Failed to get user status:', error);
}
}
// Uncomment to run an example auth check
// logUserStatus();
Errors
Common errors & fixes
Error: Cannot find module 'better-auth-devtools/client' or its corresponding type declarations.
Incorrect import path for a subpath export, or an issue with TypeScript's module resolution for `exports` field.
fixVerify the exact import path, e.g., `import { BetterAuthDevTools } from 'better-auth-devtools/client';`. For TypeScript, ensure your `tsconfig.json` has `"moduleResolution": "bundler"` or `"node16"` (or newer compatible option) to correctly resolve package `exports`. TypeError: Cannot read properties of undefined (reading 'init') or Error: require() of ES Module better-auth-devtools/react not supported.
Attempting to use CommonJS `require()` syntax with this package, which is ES Modules (ESM) only, or incorrect named import.
fixUpdate your project to use ES Modules (`import` statements) throughout. Ensure your `package.json` either has `"type": "module"` or that your bundler (Webpack, Rollup, etc.) is configured to handle ESM. Also ensure you are using named imports for `createBetterAuthDevToolsPlugin`.
React DevTools panel for Better Auth is not appearing, even after initializing the plugin.
The React DevTools browser extension might not be active, the application is not running in development mode, or the plugin initialization code is not executed within a discoverable React context.
fixEnsure the React DevTools browser extension is installed and enabled for your browser. Verify your application is running in development mode. Make sure the `createBetterAuthDevToolsPlugin` call is executed early in your React application's lifecycle, typically in your root `index.tsx` or `App.tsx` file, before any main components render.
Upgrade
Version history
0.1.1-alpha.9latest on npm
Audit
Dependencies
reactrequiredRequired for the React DevTools plugin and any React-based UI components.
react-domrequiredNecessary for rendering React components, especially within the DevTools plugin context.
better-authrequiredThe core authentication library that this devtool integrates with and provides utilities for.