Reflex DevTools is a powerful debugging toolkit for applications built with the @flexsurfer/reflex library. It provides real-time inspection of your application's state, events, and traces through an intuitive web-based dashboard.
- 📊 Database State Inspection - Visualize your entire application state in real-time
- 🔄 Real-time Event Tracing - Watch events and state changes as they happen
- 🔥 Real-time Reactions and Render Tracing - Watch all reactions being created and run, and rendering processes
- ⏱ Performance Profiling - Analyze events and reactions times and bottlenecks in real-time
- 🤖 AI-Powered Debugging - MCP integration enables AI assistants like Claude or Cursor to inspect traces and dispatch events
- 🎨 Beautiful Dashboard - Clean, modern UI with dark/light theme support
- 📱 React & React Native Support - Works seamlessly with both platforms
- ⚡ Zero Configuration - Get started with just two lines of code
npm install --save-dev @flexsurfer/reflex-devtools
# or
yarn add -D @flexsurfer/reflex-devtools
# or
pnpm add -D @flexsurfer/reflex-devtoolsAdd these lines to your app's entry point (e.g., main.tsx or App.tsx):
import { enableTracing } from '@flexsurfer/reflex';
import { enableDevtools } from '@flexsurfer/reflex-devtools';
// Enable tracing for Reflex events
enableTracing();
// Connect to devtools server
enableDevtools({
serverUrl: 'localhost:4000' // Optional: defaults to localhost:4000
});npx reflex-devtoolsOr with custom configuration:
npx reflex-devtools --port 3000 --host 0.0.0.0Navigate to http://localhost:4000 in your browser to see the DevTools dashboard.
// main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { enableTracing } from '@flexsurfer/reflex';
import { enableDevtools } from '@flexsurfer/reflex-devtools';
import App from './App';
enableTracing();
enableDevtools();
ReactDOM.createRoot(document.getElementById('root')!).render(
<React.StrictMode>
<App />
</React.StrictMode>
);enableDevtools({
serverUrl: 'localhost:3001',
enabled: process.env.NODE_ENV === 'development'
});Reflex DevTools now supports the Model Context Protocol (MCP), enabling AI assistants like Claude and Cursor to directly inspect your application traces and dispatch events!
-
Install the MCP server:
npm install -g @flexsurfer/reflex-devtools-mcp
-
Start DevTools server with MCP support:
npx reflex-devtools --mcp
Important: The
--mcpflag enables trace storage. Without it, MCP will not work. -
Configure your AI client:
For Claude Desktop (
~/Library/Application Support/Claude/claude_desktop_config.json):{ "mcpServers": { "reflex-devtools": { "command": "npx", "args": ["reflex-devtools-mcp"], "env": {} } } }For Cursor IDE (Cursor Settings →
settings.json):{ "mcp.servers": { "reflex-devtools": { "command": "npx", "args": ["reflex-devtools-mcp"], "env": {} } } } -
Restart your AI client and ask questions like:
- "What's the current app state and what user actions led to this state?"
- "Navigate to the user profile page and select the first item in the list"
- "Find slow event handlers that take longer than 100ms to execute"
- "Show me active subscriptions that might be causing unnecessary re-renders"
interface DevtoolsConfig {
serverUrl?: string; // Default: 'localhost:4000'
enabled?: boolean; // Default: true
}npx reflex-devtools [options]
Options:
-p, --port <port> Port number (default: 4000)
-h, --host <host> Host address (default: localhost)
--help Show help messageReflex DevTools consists of three main components:
┌─────────────────┐ WebSocket/HTTP ┌─────────────────┐
│ Your App │ ◀──────────────────▶ │ DevTools │
│ │ │ Server │
│ - Reflex SDK │ │ │
│ - DevTools SDK │ │ - Express API │
│ │ │ - WebSocket │
└─────────────────┘ └─────────────────┘
│
│ HTTP
▼
┌─────────────────┐
│ Web Dashboard │
│ │
│ - React UI │
│ - Real-time │
│ Updates │
└─────────────────┘
- Client SDK (
/client) - Lightweight SDK that integrates with your app - DevTools Server (
/server) - Express server with WebSocket support - Web Dashboard (
/ui) - React-based debugging interface
We welcome contributions! Here's how to get started:
- Node.js 18+
- pnpm (recommended) or npm/yarn
# Clone the repository
git clone https://github.com/flexsurfer/reflex-devtools.git
cd reflex-devtools
# Install dependencies
pnpm install
# Start development servers
pnpm devThis will start:
- DevTools server on
localhost:4000 - UI development server with hot reload on
localhost:5173 - Test app on
localhost:3000
packages/
├── reflex-devtools/ # Main package (client SDK + server)
│ ├── src/client/ # Client SDK for apps
│ ├── src/server/ # DevTools server
│ └── src/cli.ts # CLI entry point
├── reflex-devtools-mcp/ # MCP server for AI assistants
│ ├── src/tools/ # MCP tool implementations
│ └── src/cli.ts # MCP CLI entry point
├── reflex-devtool-ui/ # Web dashboard
│ └── src/ # React components
└── reflex-test-app/ # Example app for testing
# Build all packages
pnpm build
# Build specific packages
pnpm build:devtools # Build main devtools package
pnpm build:ui # Build UI dashboard
pnpm build:mcp # Build MCP server
# Run tests
pnpm test
# Start development servers
pnpm dev:ui # Start UI in development mode
pnpm dev:server # Start DevTools server (use --mcp for MCP support)
pnpm dev:testapp # Start test app
pnpm dev:mcp # Start MCP server in dev mode
pnpm start:mcp # Start MCP server (production)
# Clean all builds
pnpm clean- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes
- Test with the test app:
pnpm dev:testapp - Commit using conventional commits:
git commit -m 'feat: add amazing feature' - Push and create a Pull Request
- TypeScript for all code
- ESLint + Prettier for formatting
- Conventional Commits for commit messages
- Component-based architecture for UI
MIT License - see LICENSE file for details.
Built with ❤️ for the Reflex community. Special thanks to all contributors and the open-source projects that make this possible.
Happy Debugging! 🐛➡️✨
Made by @flexsurfer