@flotrace/runtime

Stop guessing why your React app re-renders.

FloTrace is a desktop app that shows you, live, what your React tree is doing — every render, every prop change, every state mutation, every cascade — without leaving your editor and without uploading your source code anywhere.

This package is the runtime that wires your app into the desktop. Drop it in once and you get:

• A live component tree graph — not a flat fiber list. See parent/child structure as it changes in real time.
• Render reasons that actually answer "why?" — props/state/context diffs, render frequency coloring, render-cascade tracing across files.
• All your state in one panel — Zustand, Redux, TanStack Query, Context, Router. No four browser extensions, no console.log.
• Hooks + effects, classified and diffed — 14 hook types, effect dep diffing, "did this effect re-run because X changed."
• Network → state correlation — every fetch/XHR mapped to the store update it caused.
• Copy-as-Prompt — turn any panel into an AI-ready prompt for Cursor/Claude/ChatGPT in one click.

Source code never leaves your machine. The runtime sends only metadata over ws://localhost:3457 to the desktop app.

Using React Native? Install @flotrace/runtime-native instead. This package patches fetch/XMLHttpRequest in ways that crash the RN bridge.

Download the desktop app → · Docs · Compare to React DevTools

About FloTrace Desktop

FloTrace Desktop is a free Electron app (macOS / Windows / Linux) that visualizes your React app's component hierarchy in real time. This runtime package is the bridge: drop <FloTraceProvider> into your app and the desktop renders the live tree, with full inspection of props, hooks, effects, state, network calls, and render cascades.

When @flotrace/runtime (this package) is paired with the desktop, you get:

• Live component tree — React Flow graph, render-flash animation, frequency-based heatmap, breadcrumb bar, search-with-fitView.
• Per-node inspection — props (with diff history), hooks (14 classified types + dep diffs), effects (willRun + dep diffs), component timeline.
• State tracking — Zustand (per-store), Redux (with change highlighting), Router, TanStack Query (with health warnings + wasted-refetch detection), Context.
• Render cascade tracing — trigger log, cascade tree, flame chart, cascade compare modal.
• Prop drilling detection — chain detection (≥3 levels deep), severity badges, heatmap overlay, refactor recommendations.
• Network health — fetch / XHR tracking, method badges, status dots, duplicate detection, API → store causal correlation, pin-to-watch.
• React 19 + Next.js — Actions monitor, concurrent-update signals (useTransition / Suspense), compiler memo health, Next.js App Router detection, RSC payload interception.
• Watch expressions — pin values from 8 sources (Zustand / Redux / Router / Context / Props / Hooks / TanStack Query / API), max 20.
• AI Code Review Dashboard — 6-tab review (Re-renders, Memo, Drilling, Effects, Compiler, Network) with Lighthouse-style scores.
• Copy-as-Prompt — turn any panel into an AI-ready prompt for Cursor / Claude / ChatGPT in one click.

How it fits together:

your React app  ←→  @flotrace/runtime  ←→  ws://localhost:3457  ←→  FloTrace Desktop
                       (this package — open source, MIT)         (closed-source commercial)

The desktop is free and binds to 127.0.0.1 only by default — your source code, props, and state never leave your machine.

30-second setup

npm install -D @flotrace/runtime

import { FloTraceProvider } from '@flotrace/runtime';
import { createRoot } from 'react-dom/client';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <FloTraceProvider config={{ appName: 'My App' }}>
    <App />
  </FloTraceProvider>
);

Launch the FloTrace desktop app. Reload your dev server. Done — your tree appears.

Peer dependencies: React >= 16.9.0 (uses <Profiler> API). Auto-disables in production via process.env.NODE_ENV.

Framework recipes

Next.js (App Router)

// app/providers.tsx
'use client';
import { FloTraceProvider } from '@flotrace/runtime';

export function Providers({ children }: { children: React.ReactNode }) {
  return <FloTraceProvider config={{ appName: 'My Next.js App' }}>{children}</FloTraceProvider>;
}

// app/layout.tsx
import { Providers } from './providers';
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <html><body><Providers>{children}</Providers></body></html>;
}

Next.js (Pages Router)

// pages/_app.tsx
import { FloTraceProvider } from '@flotrace/runtime';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <FloTraceProvider config={{ appName: 'My Next.js App' }}>
      <Component {...pageProps} />
    </FloTraceProvider>
  );
}

Vite / Create React App

Same as the 30-second setup above — wrap <App /> at the root.

Source attribution (click-to-IDE)

Exact file:line:column attribution on every component powers click-to-IDE, breadcrumb file pills, Hot Call Sites, and accurate user-vs-framework differentiation. Most web apps need zero config — Next.js (SWC) and Vite pick it up from jsxImportSource plus React's own debug info:

// tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@flotrace/runtime-core"
  }
}

The optional Babel plugin (ships inside this package — no extra install) adds two things jsxImportSource can't: attribution for Create React App (whose locked Babel config ignores jsxImportSource) and definition-site attribution for components instantiated via React.createElement(C) from a library (react-router v5 <Route component={X}>, HOCs):

// babel.config.js (or the babel section of your bundler config)
module.exports = {
  env: {
    development: {
      plugins: ['@flotrace/runtime/babel-plugin'],
    },
  },
};

The env.development block keeps it dev-only — production bundles stay clean. Restart the dev server with --reset-cache after adding it. (React Native projects use @flotrace/runtime-native/babel-plugin instead — it's the same plugin, re-exported from each adapter.)

Create React App ignores a project-level babel.config.js — its Babel config is locked. To add the plugin you need CRACO or react-app-rewired. With CRACO, add it under babel.plugins in craco.config.js:

// craco.config.js
module.exports = {
  babel: {
    plugins:
      process.env.NODE_ENV === 'development' ? ['@flotrace/runtime/babel-plugin'] : [],
  },
};

Wire up your state stores

State tracking is the killer feature. Pass your stores to the provider and they show up in the desktop's State panel with live diffs:

import { FloTraceProvider } from '@flotrace/runtime';
import { useBearStore } from './zustandStore';
import { store as reduxStore } from './reduxStore';
import { queryClient } from './queryClient';

<FloTraceProvider
  config={{ appName: 'My App' }}
  stores={{ bearStore: useBearStore }}     // Zustand — keys become store names
  reduxStore={reduxStore}                   // Redux — pass your store directly
  queryClient={queryClient}                 // TanStack Query — pass your client
>
  <App />
</FloTraceProvider>

Router tracking is automatic — it patches the History API and works with React Router, TanStack Router, Next.js, etc.

Configuration

All options optional. Sensible defaults for development.

| Option | Type | Default | Description | |--------|------|---------|-------------| | appName | string | 'React App' | Shown in the FloTrace connection pill | | port | number | 3457 | WebSocket server port | | enabled | boolean | dev only | false to hard-disable | | autoReconnect | boolean | true | Reconnect on disconnect | | reconnectInterval | number | 2000 | Base reconnect delay (ms, exponential backoff) | | trackAllRenders | boolean | true | Track every commit via <Profiler> | | includeProps | boolean | true | Include prop values in render events | | trackZustand / trackRedux / trackRouter / trackContext / trackTanstackQuery | boolean | true | Per-tracker toggles |

Production safety

FloTrace is disabled in production by default (enabled defaults to process.env.NODE_ENV === 'development'). For belt-and-braces tree-shaking, dynamic-import in dev only:

const FloTraceProvider = process.env.NODE_ENV === 'development'
  ? (await import('@flotrace/runtime')).FloTraceProvider
  : ({ children }: { children: React.ReactNode }) => <>{children}</>;

Targeted profiling

For one-off component tracking without the full provider:

import { withFloTrace, useTrackProps } from '@flotrace/runtime';

const Profiled = withFloTrace(MyComponent, 'MyComponent');

function MyComponent(props: MyProps) {
  useTrackProps('MyComponent', props);
  // ...
}

Privacy & security

• Source code never leaves your machine. The runtime sends only metadata (component names, prop types, render counts) over ws://localhost:3457.
• Desktop app binds to 127.0.0.1 only. LAN connections (physical devices) require an opt-in auth token.
• The desktop is closed-source commercial; this runtime package is MIT-licensed and open at github.com/sameersitre/runtime.

Troubleshooting

"Not connected" — Is the desktop app running? Is enabled: true? Check browser console for [FloTrace] logs.

Zustand stores missing — Stores must be passed via the stores prop, and each value must be a Zustand hook (has .getState() and .subscribe()).

Tree empty or partial — Reload the page. The walker uses React DevTools hook or DOM-based fiber access; depth is capped at 100, children at 300/node.

WebSocket reconnecting — Exponential backoff (2s → 30s, 10 attempts). After that, reload the page or restart the desktop.

API reference

See flotrace.dev/docs/runtime for the full export surface (40+ hooks, trackers, and types). Quick index:

| Export | Description | |---|---| | FloTraceProvider | Main provider component | | withFloTrace(Component, name?) | HOC for targeted profiling | | useFloTrace() | Connection state + config | | useTrackProps(name, props) | Track prop changes | | installXxxTracker() / uninstallXxxTracker() | Manual tracker control (Zustand, Redux, Router, TanStack Query, Network, Timeline) | | getNodeHooks(nodeId) / getNodeEffects(nodeId) / getDetailedRenderReason(nodeId) | Inspector accessors |

Type exports: FloTraceConfig, LiveTreeNode, SerializedValue, HookInfo, EffectInfo, TimelineEvent, NetworkRequestEntry, Fiber, etc.

License

MIT — see LICENSE. Issues and PRs welcome at github.com/sameersitre/runtime.

Mirrored from the flotrace-desktop monorepo. This repo is read-only — every release is regenerated by the lockstep publisher in the desktop monorepo. Issues filed here are tracked, but PRs are best opened against the upstream monorepo where the canonical source lives.