TanStack Router DevTools — React Deep Dive

one panel, the whole router

Drop <TanStackRouterDevtools router={router}/> once (dev-only) and you get a floating panel that mirrors the router's live state. Four tabs cover the full surface: Route Tree (parent→child, eager vs lazy, matched chain highlighted), Match Inspector (params, validated search, context, loader status), Navigation History (timeline + preload hits/misses + redirect chains), Performance (match time, loader time, render time). It is read-only — it subscribes to router.state and never mutates it.

tab	shows	answers the question
`Route Tree`	full tree, eager/lazy badges, matched chain highlighted	"which routes exist, and which ones are live right now?"
`Match`	pathname, params, validated search, context, loader status	"what did the router extract from THIS url?"
`History`	past navigations, preload hit/miss, redirect chains	"how did the user get here, and was anything prefetched?"
`Performance`	match time, loader exec time, component render time	"where is this navigation spending time?"

1 · the DevTools panel (edit me)

This is a faithful simulation of the four-tab panel. In a real app the data comes from router.state subscriptions; here it is a static routerState snapshot so you can see exactly what each tab renders. Edit and hit "compile & render".

// Simulated router state — the exact shape the real DevTools mirrors.
var routerState = {
  routes: [
    { path: '/', name: 'Root', type: 'eager' },
    { path: '/users', name: 'Users', type: 'eager' },
    { path: '/users/$id', name: 'UserDetail', type: 'lazy' },
    { path: '/settings', name: 'Settings', type: 'eager' }
  ],
  currentMatch: {
    pathname: '/users/42',
    matchedChain: ['Root', 'Users', 'UserDetail'],
    params: { id: '42' },
    search: { tab: 'posts' },
    context: { user: 'admin', theme: 'dark' },
    loaderStatus: 'loaded',
    matchTime: '2.3ms',
    loaderTime: '45ms'
  },
  navigationHistory: [
    { from: '/', to: '/users', preload: 'hit', time: '12:01:00' },
    { from: '/users', to: '/users/42', preload: 'miss', time: '12:01:03' }
  ],
  performance: {
    matchTime: '2.3ms',
    loaderTime: '45ms',
    renderTime: '8.1ms'
  }
};

function DevToolsPanel() {
  var _React$useState = React.useState('routes'),
      activeTab = _React$useState[0],
      setActiveTab = _React$useState[1];

  var tabs = [
    { id: 'routes', label: 'Route Tree' },
    { id: 'match', label: 'Match' },
    { id: 'history', label: 'History' },
    { id: 'performance', label: 'Performance' }
  ];

  return (
    <div data-testid="devtools-panel" className="rounded-xl border border-[#30363d] bg-[#0d1117] shadow-2xl overflow-hidden">
      <div className="flex items-center gap-2 px-4 py-2 bg-[#161b22] border-b border-[#30363d]">
        <span className="text-[#61dafb] font-bold text-sm">⚡ TanStack Router DevTools</span>
        <span className="ml-auto text-[#8b949e] text-[10px] uppercase tracking-wide border border-[#30363d] rounded px-1.5 py-0.5">dev only</span>
      </div>
      <div data-testid="tab-bar" className="flex border-b border-[#30363d]">
        {tabs.map(function (tab) {
          var active = tab.id === activeTab;
          return (
            <button
              key={tab.id}
              data-testid={'tab-' + tab.id}
              data-tab={tab.id}
              data-active={active ? 'true' : 'false'}
              onClick={function () { setActiveTab(tab.id); }}
              className={'px-4 py-2 text-xs font-semibold border-b-2 transition-colors ' + (active ? 'border-[#61dafb] text-[#61dafb]' : 'border-transparent text-[#8b949e] hover:text-[#e6edf3]')}
            >
              {tab.label}
            </button>
          );
        })}
      </div>
      <div data-testid="tab-content" className="p-4 min-h-[200px]">
        {activeTab === 'routes' && <RouteTreeView />}
        {activeTab === 'match' && <MatchInspectorView />}
        {activeTab === 'history' && <HistoryView />}
        {activeTab === 'performance' && <PerformanceView />}
      </div>
    </div>
  );
}

function RouteTreeView() {
  var matchedSet = {};
  routerState.currentMatch.matchedChain.forEach(function (n) { matchedSet[n] = true; });
  return (
    <div data-testid="route-tree">
      <p className="text-[#8b949e] text-[11px] mb-2 uppercase tracking-wide">route tree · matched chain highlighted</p>
      <ul data-testid="route-list" className="space-y-1 text-xs font-mono">
        {routerState.routes.map(function (route) {
          var matched = matchedSet[route.name];
          var lazy = route.type === 'lazy';
          return (
            <li
              key={route.path}
              data-testid="route-item"
              data-name={route.name}
              data-matched={matched ? 'true' : 'false'}
              className={'flex items-center gap-2 px-2 py-1.5 rounded border ' + (matched ? 'bg-[rgba(97,218,251,.12)] border-[rgba(97,218,251,.4)] text-[#61dafb]' : 'bg-[#161b22] border-[#30363d] text-[#e6edf3]')}
            >
              <span className={matched ? 'text-[#61dafb]' : 'text-[#8b949e]'}>{matched ? '▸' : ' '}</span>
              <span className="font-mono">{route.path}</span>
              <span className="ml-auto">{route.name}</span>
              <span
                data-testid="route-type"
                data-type={route.type}
                className={'px-1.5 py-0.5 rounded text-[10px] font-bold uppercase ' + (lazy ? 'bg-[rgba(231,76,60,.15)] text-[#e74c3c]' : 'bg-[rgba(46,204,113,.15)] text-[#2ecc71]')}
              >{route.type}</span>
            </li>
          );
        })}
      </ul>
    </div>
  );
}

function MatchInspectorView() {
  var m = routerState.currentMatch;
  function Row(props) {
    return (
      <div className="grid grid-cols-[90px_1fr] gap-2 items-start py-1.5 border-b border-[#30363d]">
        <span className="text-[#8b949e] text-[11px] uppercase tracking-wide">{props.label}</span>
        <code data-testid={props.testId} className="text-[#61dafb] text-xs break-all">{props.value}</code>
      </div>
    );
  }
  return (
    <div data-testid="match-inspector">
      <p className="text-[#8b949e] text-[11px] mb-2 uppercase tracking-wide">current match · /users/42</p>
      <Row label="pathname" testId="match-pathname" value={m.pathname} />
      <Row label="params" testId="match-params" value={JSON.stringify(m.params)} />
      <Row label="search" testId="match-search" value={JSON.stringify(m.search)} />
      <Row label="context" testId="match-context" value={JSON.stringify(m.context)} />
      <Row label="loader" testId="match-loader" value={m.loaderStatus} />
      <Row label="chain" testId="match-chain" value={m.matchedChain.join(' → ')} />
    </div>
  );
}

function HistoryView() {
  return (
    <div data-testid="history">
      <p className="text-[#8b949e] text-[11px] mb-2 uppercase tracking-wide">navigation history · preload hits/misses</p>
      <ul data-testid="history-list" className="space-y-2 text-xs font-mono">
        {routerState.navigationHistory.map(function (entry, i) {
          var hit = entry.preload === 'hit';
          return (
            <li
              key={i}
              data-testid="history-item"
              data-preload={entry.preload}
              className="flex items-center gap-2 px-2 py-1.5 rounded bg-[#161b22] border border-[#30363d]"
            >
              <span className="text-[#8b949e] w-20">{entry.time}</span>
              <span className="text-[#e6edf3]">{entry.from}</span>
              <span className="text-[#61dafb]">→</span>
              <span className="text-[#e6edf3]">{entry.to}</span>
              <span
                className={'ml-auto px-1.5 py-0.5 rounded text-[10px] font-bold uppercase ' + (hit ? 'bg-[rgba(46,204,113,.15)] text-[#2ecc71]' : 'bg-[rgba(231,76,60,.15)] text-[#e74c3c]')}
              >preload:{entry.preload}</span>
            </li>
          );
        })}
      </ul>
    </div>
  );
}

function PerformanceView() {
  var p = routerState.performance;
  var metrics = [
    { label: 'Route match', testId: 'perf-match', value: p.matchTime },
    { label: 'Loader exec', testId: 'perf-loader', value: p.loaderTime },
    { label: 'Component render', testId: 'perf-render', value: p.renderTime }
  ];
  return (
    <div data-testid="performance">
      <p className="text-[#8b949e] text-[11px] mb-2 uppercase tracking-wide">performance · per-match timing</p>
      <div className="space-y-2">
        {metrics.map(function (metric) {
          return (
            <div
              key={metric.testId}
              data-testid={metric.testId}
              className="flex items-center gap-3 px-3 py-2 rounded bg-[#161b22] border border-[#30363d]"
            >
              <span className="text-[#8b949e] text-[11px] uppercase tracking-wide flex-1">{metric.label}</span>
              <span className="text-[#61dafb] text-sm font-bold">{metric.value}</span>
            </div>
          );
        })}
      </div>
    </div>
  );
}

function App() {
  return (
    <div className="space-y-3">
      <div data-testid="app-bar" className="flex items-center gap-3 px-4 py-2 bg-[#161b22] rounded-lg border border-[#30363d]">
        <span className="text-[#e6edf3] text-sm font-semibold">My App</span>
        <span className="text-[#8b949e] text-xs">current: {routerState.currentMatch.pathname}</span>
        <span className="ml-auto text-[#8b949e] text-[10px]">⟵ the panel below is the DevTools</span>
      </div>
      <p className="text-[#8b949e] text-xs">
        Real DevTools floats at <b className="text-[#e6edf3]">bottom-right</b> over your app; here it is
        inlined into the playground so the gold-check can inspect it.
      </p>
      <DevToolsPanel />
    </div>
  );
}

createRoot(document.getElementById('root')).render(<App/>);

2 · Babel compiles JSX → element tree

<DevToolsPanel/> becomes React.createElement(DevToolsPanel). Each setActiveTab(id) re-renders only the panel; the simulated routerState is static so the data the tabs show is stable.

// (hit "compile & render" to see Babel's output)

3 · live React (the panel, proven)

The gold-check clicks through every tab automatically: asserts the panel rendered, the Route Tree shows 4 routes, the Match tab shows params id=42 + search tab=posts, the History tab shows ≥2 entries, and the Performance tab shows match + loader times.

active tab: — · gold: routes(4) → match(id=42, tab=posts) → history(≥2) → perf(match+loader)

intent → tab / pattern

intent	pattern	why
mount DevTools	`<TanStackRouterDevtools router={router} position="bottom-right"/>`	one mount, dev-only; subscribes to `router.state`
hide in prod	`process.env.NODE_ENV === 'development' && <Devtools/>`	the package is dev-only; never ship it to users
position the logo	`position="top-left\|top-right\|bottom-left\|bottom-right"`	defaults to `bottom-left`; the trigger logo floats over the app
"why did this route match?"	Route Tree tab → matched-chain highlight	shows eager vs lazy + the ancestor chain the URL activated
"what params/search did it extract?"	Match tab → params / search rows	validated search = post-`validateSearch` values, not raw query string
"did the preload fire?"	History tab → preload hit/miss badge	correlates intent-hover/preload with the actual navigation
"why is navigation slow?"	Performance tab → match / loader / render times	splits time across the three pipeline stages