Skip to main content

​
Overview

Watch mode automatically monitors your auth.ts configuration file and reloads the Better Auth Studio server when changes are detected. This provides a seamless development experience when iterating on your authentication setup.

​
Enabling Watch Mode

Start the studio with the --watch flag: 
pnpx better-auth-studio start --watch
Watch mode is perfect for active development when you’re frequently updating your auth configuration.

​
How It Works

1

File Monitoring

Watch mode uses chokidar to monitor your auth config file for any changes.
# Terminal output when watch mode starts
✔ Better Auth Studio is running!
👀 Watch mode enabled - config changes will reload automatically
2

Change Detection

When you save changes to your auth config file, the studio detects them immediately.
# Terminal output on file change
↻ Reloading Better Auth Studio (changed src/auth.ts)
3

Server Reload

The server automatically:
  • Closes the current instance
  • Reloads the auth configuration
  • Restarts the server
  • Maintains the same port and host
4

Browser Update

The browser UI updates automatically via WebSocket connection (no manual refresh needed).
# Terminal output on reload complete
✔ Reload complete (src/auth.ts)

​
WebSocket Integration

Watch mode uses WebSocket to provide real-time updates to the browser:

​
Connection Lifecycle

// WebSocket connection established automatically
{
  type: "connected",
  message: "Connected to Better Auth Studio (watch mode)"
}

​
Status Messages

The studio sends status updates during reload: 
{
  "type": "studio_status",
  "status": "up_to_date",
  "updatedAt": 1234567890,
  "fileName": "auth.ts",
  "filePath": "src/auth.ts"
}
Server is running and ready to accept requests.
{
  "type": "studio_status",
  "status": "refreshing",
  "updatedAt": 1234567890,
  "fileName": "auth.ts",
  "filePath": "src/auth.ts"
}
Server is reloading due to config changes.
{
  "type": "studio_status",
  "status": "error",
  "updatedAt": 1234567890,
  "message": "Unable to reload auth configuration.",
  "fileName": "auth.ts",
  "filePath": "src/auth.ts"
}
Server encountered an error during reload.

​
Change Events

{
  "type": "config_change_detected",
  "message": "Auth configuration change detected",
  "fileName": "auth.ts",
  "filePath": "src/auth.ts",
  "changedAt": 1234567890
}

​
Configuration

​
With Custom Config Path

Watch mode works with custom config paths: 
pnpx better-auth-studio start --watch --config ./src/lib/auth.ts
The studio will monitor the specified file for changes.

​
With Other Options

Combine watch mode with other CLI options: 
# Watch mode with custom port
pnpx better-auth-studio start --watch --port 3001

# Watch mode without auto-opening browser
pnpx better-auth-studio start --watch --no-open

# Full configuration
pnpx better-auth-studio start \
  --watch \
  --config ./src/lib/auth.ts \
  --port 3001 \
  --host localhost

​
Terminal Output Examples

​
Successful Reload

↻ Reloading Better Auth Studio (changed src/auth.ts)
✔ Reload complete (src/auth.ts)

​
Failed Reload

↻ Reloading Better Auth Studio (changed src/auth.ts)
✖ Reload failed (src/auth.ts) - Unable to reload auth configuration.
If reload fails, the previous server instance remains running. Fix the configuration error and save again to retry.

​
Auto-Detection Warning

If the auth config file cannot be located: 
⚠ Unable to locate your auth config file. Watch mode will be disabled for this session.
Use the --config flag to specify the exact path to your auth configuration file.

​
Heartbeat & Connection Management

Watch mode maintains WebSocket connections with automatic heartbeat: 
// Heartbeat ping every 30 seconds
setInterval(() => {
  if (ws.readyState === ws.OPEN) {
    ws.ping();
  }
}, 30000);
Benefits:
  • Keeps connections alive
  • Detects disconnected clients
  • Automatically cleans up closed connections

​
Use Cases

Plugin Development

Test Better Auth plugins in real-time as you develop them.

Provider Configuration

Iterate on OAuth provider settings and see changes immediately.

Database Changes

Switch between database adapters and test configurations.

Security Settings

Adjust security options and verify them instantly.

​
Best Practices

​
During Active Development

1

Enable watch mode

pnpx better-auth-studio start --watch
2

Edit your auth config

Make changes to auth.ts and save the file.
3

Verify in browser

The browser UI updates automatically - no refresh needed.

​
For Production Testing

Do not use watch mode in production. It’s designed for development only.
For production deployments:
  1. Use self-hosting setup
  2. Disable watch mode
  3. Implement proper deployment strategies
See Self-Hosting for production setup.

​
Troubleshooting

​
Watch Mode Not Working

Problem: ⚠ Unable to locate your auth config fileSolution:
# Specify config path explicitly
pnpx better-auth-studio start --watch --config ./src/auth.ts
Problem: ✖ Reload failed - Unable to reload auth configurationSolutions:
  • Check for syntax errors in auth.ts
  • Verify all imports are valid
  • Check terminal for detailed error messages
  • Ensure database connection is still active
Problem: UI doesn’t reflect config changesSolutions:
  • Check browser console for WebSocket errors
  • Verify WebSocket connection is established
  • Try manually refreshing the page
  • Restart the studio server
Problem: Server reloads too frequentlySolutions:
  • Wait for reload to complete before making more changes
  • Disable auto-save in your editor temporarily
  • The studio includes a 75ms debounce to prevent excessive reloads

​
WebSocket Connection Issues

If WebSocket connections fail:
  1. Check firewall settings - Ensure WebSocket connections are allowed
  2. Verify port availability - Make sure the port isn’t blocked
  3. Browser compatibility - Use a modern browser with WebSocket support
  4. Network proxy - Some proxies may block WebSocket connections

​
Graceful Shutdown

Watch mode handles shutdown gracefully: 
Press Ctrl+C to stop the studio
On shutdown, the server:
  1. Closes the file watcher
  2. Terminates WebSocket connections
  3. Shuts down the HTTP server
  4. Exits cleanly

​
Performance Considerations

​
File Watching

  • Efficient: Uses chokidar for optimal file system monitoring
  • Selective: Only watches the auth config file, not the entire project
  • Low overhead: Minimal CPU/memory impact during idle periods

​
Reload Speed

Typical reload times:
  • Detection: <10ms (instant)
  • Server restart: 50-200ms
  • Config reload: 100-500ms (depends on complexity)
  • Total: Usually under 1 second
The 75ms delay before reload helps batch multiple rapid file saves into a single reload.

​
Next Steps

CLI Usage

Explore all CLI options and commands

Custom Branding

Customize studio appearance

Troubleshooting

Common issues and solutions

Self-Hosting

Production deployment guide

Build docs developers (and LLMs) love

Get started for freeTalk to us