Better Auth DevTools

Common errors

• Error: Cannot find module 'better-auth-devtools/client' or its corresponding type declarations.

  cause Incorrect import path for a subpath export, or an issue with TypeScript's module resolution for `exports` field.
  fix Verify 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.

  cause Attempting to use CommonJS `require()` syntax with this package, which is ES Modules (ESM) only, or incorrect named import.
  fix Update 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.

  cause 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.
  fix Ensure 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.

Warnings

• breaking This package is currently in an alpha state (version 0.1.1-alpha.9). Expect frequent breaking changes, API instability, and unannounced modifications between releases without major version bumps. It is not recommended for production environments.
  Fix: Monitor GitHub releases and changelogs closely for updates. Pin exact alpha versions in `package.json` to prevent unexpected breakage, but be prepared for manual upgrades.
• gotcha As an unofficial devtool for Better Auth, its feature set or API might not always align with future official Better Auth library updates or support policies. It's maintained independently.
  Fix: Always test `better-auth-devtools` thoroughly after updating the core `better-auth` package. Report any incompatibilities to the `better-auth-devtools` maintainers.
• gotcha This library has critical peer dependencies on `react`, `react-dom`, and `better-auth`. Mismatches in versions can lead to runtime errors, silent failures, or unexpected behavior, especially with React's context system or `better-auth`'s internal state.
  Fix: Ensure that your project's installed versions of `react`, `react-dom`, and `better-auth` satisfy the peer dependency requirements specified in `better-auth-devtools`'s `package.json`. Use `npm install` or `yarn install` to resolve peer dependencies.

Install

• npm install better-auth-devtools npm
• yarn add better-auth-devtools yarn
• pnpm add better-auth-devtools pnpm

Imports

• BetterAuthDevTools
  wrong:

  const { BetterAuthDevTools } = require('better-auth-devtools/client');

  correct:

  import { BetterAuthDevTools } from '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
  wrong:

  import createBetterAuthDevToolsPlugin from 'better-auth-devtools/react';

  correct:

  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
  wrong:

  const { createBetterAuthDevToolsPlugin } = require('better-auth-devtools');

  correct:

  import { createBetterAuthDevToolsPlugin } from '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.

Quickstart

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();