react-dev-bot

1.2.1 verified Mon Apr 27 auth: no javascript

Vite/Next.js plugin that embeds an AI (Claude Code) chat panel and component inspector in the browser during development. Version 1.2.1 integrates with Claude Code CLI for conversational debugging, screenshot capture, click history, and editor-to-browser component inspection. Compatible with Vite 5+ and Next.js 14+ (App Router), though the component inspector's original path resolution is currently limited to Next.js 16. The plugin requires local Claude Code CLI and offers optional error boundaries for React render errors. Release cadence is irregular; primarily maintained by a small team.

Common errors

error Error: Cannot find module 'react-dev-bot/vite' ↓

cause Installed package does not include the 'vite' subpath export or package is older version.

fix

Update package to latest: pnpm add -D react-dev-bot@latest.

error Error: The inspectorCursorServer plugin requires VITE_LOCATOR=true and sourcemaps to be enabled. ↓

cause Missing environment variable or sourcemap configuration in vite.config.ts.

fix

Set VITE_LOCATOR=true in .env.development and enable build.sourcemap: 'hidden' in Vite config.

error Error: The devBot plugin is only available in development mode. ↓

cause devBot() was added to plugins array outside of development mode check.

fix

Wrap devBot() in ...(mode === 'development' ? [devBot()] : []).

error Error: Route "app/api/dev/[...path]/route.ts" does not match the route handler. ↓

cause Missing or incorrectly placed catch-all route file.

fix

Create app/api/dev/[...path]/route.ts and export GET/POST from react-dev-bot/next/route.

error Error: DevBot is not defined (Next.js build error) ↓

cause Import of DevBot from incorrect path; must be from 'react-dev-bot/next'.

fix

Use import { DevBot } from 'react-dev-bot/next' instead of from top-level package.

Warnings

breaking Component inspector original path resolution currently works only with Next.js 16 (Turbopack/Webpack). Next.js 13–15 may show bundle paths instead. ↓

fix Upgrade to Next.js 16 for full inspector functionality, or wait for future support for older versions.

breaking Peer dependency on Vite >=5.0.0 and Next.js >=14.0.0; using older versions may cause runtime errors. ↓

fix Ensure Vite 5+ or Next.js 14+ is installed.

deprecated Importing `devBot` from `'react-dev-bot'` (top-level) is deprecated; prefer `'react-dev-bot/vite'`. ↓

fix Change import to `import { devBot } from 'react-dev-bot/vite'`.

gotcha DevBot component renders nothing in production (NODE_ENV !== 'development'). To test in production, use the `force` prop on DevBotErrorBoundary. (Not available on DevBot itself.) ↓

fix DevBot is always production-safe; for error boundary, use `<DevBotErrorBoundary force>`.

gotcha Security: if DEVBOT_REQUIRE_TOKEN is not set to '1', the plugin falls back to same-origin checks (Origin header). In some configurations (e.g., reverse proxy), this may allow unauthorized access. ↓

fix Set `DEVBOT_REQUIRE_TOKEN=1` and define a strong `DEVBOT_TOKEN` environment variable.

gotcha The DEVBOT_TOKEN is printed to stderr on each dev server start if not set manually. Do not commit `.env.development` with a hardcoded token to public repos. ↓

fix Use environment-specific .env files or CI secrets to manage tokens.

Install

npm install react-dev-bot

yarn add react-dev-bot

pnpm add react-dev-bot

Imports

devBot
wrong
```
import { devBot } from 'react-dev-bot'
```
correct
```
import { devBot } from 'react-dev-bot/vite'
```
Legacy import from 'react-dev-bot' still works but is not recommended; prefer '/vite' for clarity.

DevBot

wrong

import { DevBot } from 'react-dev-bot'

correct

import { DevBot } from 'react-dev-bot/next'

React component for Next.js; must be imported from '/next' subpath.

DevBotErrorBoundary
```
import { DevBotErrorBoundary } from 'react-dev-bot/next'
```
Optional error boundary for React render errors; only active in development by default.
GET
wrong
```
import { GET } from 'react-dev-bot/next/route'
```
correct
```
export { GET } from 'react-dev-bot/next/route'
```
Re-export for Next.js API route handler; must be used in route.ts file with catch-all path.

POST

export { POST } from 'react-dev-bot/next/route'

Same as GET above, for POST requests.

inspectorCursorServer
```
import { inspectorCursorServer } from 'react-dev-bot/vite'
```
Vite plugin for sourcemap-based component locator; requires VITE_LOCATOR=true and sourcemaps enabled.

Quickstart

Minimal setup for both Vite and Next.js projects: install package, configure plugins/routes, mount DevBot component, and start dev server.

# Install as dev dependency
pnpm add -D react-dev-bot

# Ensure Claude Code CLI is available in PATH
claude --version

# Set up environment variables in .env.development
VITE_LOCATOR=true
REACT_EDITOR=cursor

# Vite: configure vite.config.ts
import { defineConfig, loadEnv } from 'vite';
import react from '@vitejs/plugin-react-swc';
import { devBot, inspectorCursorServer } from 'react-dev-bot/vite';

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');
  const locatorEnabled = env.VITE_LOCATOR === 'true';
  if (env.REACT_EDITOR) process.env.REACT_EDITOR = env.REACT_EDITOR;

  return {
    build: {
      sourcemap: locatorEnabled ? 'hidden' : false,
      ...(locatorEnabled && {
        rollupOptions: { output: { sourcemapExcludeSources: true } },
      }),
    },
    plugins: [
      ...(locatorEnabled ? [inspectorCursorServer()] : []),
      ...(mode === 'development' ? [devBot()] : []),
      react(),
    ],
  };
});

# Next.js: add API route at app/api/dev/[...path]/route.ts
// app/api/dev/[...path]/route.ts
export { GET, POST } from 'react-dev-bot/next/route';

# Next.js: mount DevBot in root layout
// app/layout.tsx
import { DevBot } from 'react-dev-bot/next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <DevBot />
        {children}
      </body>
    </html>
  );
}

# Start dev server
pnpm dev
# On startup, a random token is printed to stderr if DEVBOT_TOKEN not set.
# Open browser and look for the DevBot panel (usually bottom-right corner).