React Switchboard 🎛

Quickly create custom DevTools for your React app.

• Live Demo 🚀
• Demo repo using Vite

Quick Start

npm install react-switchboard -D

Vite Example

Call Switchboard in your project root. Pass your app's main component to Switchboard's appSlot prop. Import Switchboard CSS. Lazy load Switchboard via an environment variable so it's excluded from your production bundle.

import { lazy } from "react";
import { createRoot } from "react-dom/client";
import "react-switchboard/dist/index.css";

const Switchboard = lazy(() => import("react-switchboard"));

createRoot(document.getElementById("root")!).render(
  import.meta.env.PROD ? (
    <App />
  ) : (
    <Suspense fallback="Loading Switchboard...">
      <Switchboard appSlot={<App />} />
    </Suspense>
  )
);

Headless

The Switchboard component accepts children so you can specify what it renders. If you want complete control over the UI, use the useSwitchboard and useSwitchboardState hooks instead of the Switchboard component.

function CustomSwitchboard() {
  const { generalSettings, switchboardWindowRef, copySettingsUrlToClipboard } =
    useSwitchboard();

  // Use useSwitchboardState hook for custom settings.
  const [user, setUser] = useSwitchboardState("sb-user", null);

  return {
    /* Your custom JSX to render your desired UI */
  };
}

Why Switchboard?

Code faster. Reproduce edge cases. Do real-time demos. Use Switchboard to configure automated tests.

Common Uses

• Login / switch users instantly
• Change feature toggles
• Configure mock APIs
• Force errors
• Simulate network slowness for specific requests
• Configure automated test scenarios
• Simulate incoming traffic and write conflicts

More info in this 25 minute conference talk: Creating Custom Dev Tools for Your React App at React Rally

API

Components

• Switchboard - The main component that renders your app and the Switchboard UI.

Hooks

• useSwitchboard - Logic for running Switchboard. Useful to create a custom Switchboard UI.
• useSwitchboardState - Declare Switchboard state. This state is automatically initialized from the URL, and written to localStorage so that it persists between sessions. Useful to extend Switchboard's features with custom settings for your app, or if you want to create a custom Switchboard UI.

FAQ

• How does mocking work? Switchboard intercepts fetch requests via Mock Service Worker, and displays a UI for configuring the mock responses.

• Why does Switchboard render my app? If you configure Switchboard to force the app to throw an error, Switchboard continues to render so you can change Switchboard's settings.

• Why lazy loading? Lazy load Switchboard via React.lazy and Suspense so that it's excluded your app's prod bundle.

• How can I toggle Switchboard? Use an environment variable to enable Switchboard. For example, tweak Vite's dev npm script to set an environment variable using cross-env:

"dev": "cross-env VITE_ENABLE_SWITCHBOARD=Y vite",

Then, read this environment variable in your app's entry point.

Acknowledgements

• Mock Service Worker - Switchboard mocks HTTP requests via msw.

Inspiration

• React Query Devtools
• https://github.com/dataarts/dat.gui