Chapter 3: Devtools

Core Idea

TanStack Router ships dedicated devtools, installed as a separate package, that visualize the router's internal state; they can be rendered in Floating, Fixed, or Embedded mode, and are excluded from production builds unless the explicit *InProd variant is used.

Key Concepts

• @tanstack/react-router-devtools: The separate package to install (Solid: @tanstack/solid-router-devtools).
• TanStackRouterDevtools: The default import; automatically hidden when process.env.NODE_ENV === 'production'.
• TanStackRouterDevtoolsInProd: Same API as TanStackRouterDevtools but renders even in production environments.
• Floating Mode: Mounts devtools as a fixed, floating element with a toggle button; open/closed state persists in localStorage across reloads.
• Fixed Mode: Uses TanStackRouterDevtoolsPanel directly, allowing attachment to a specific Shadow DOM target for custom positioning.
• Embedded Mode: Renders TanStackRouterDevtoolsPanel as a normal component that can be styled freely via style/className (Solid: class).
• Manual router prop: Devtools accept a router prop matching the instance passed to RouterProvider, allowing placement anywhere on the page, not just inside the provider.

Code Examples

// src/routes/__root.tsx
import { createRootRoute, Outlet } from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'

export const Route = createRootRoute({
  component: () => (
    <>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
})

• What it demonstrates: The simplest way to wire devtools into the root route so they auto-connect to the router instance.

function App() {
  return (
    <>
      <RouterProvider router={router} />
      <TanStackRouterDevtools initialIsOpen={false} />
    </>
  )
}

• What it demonstrates: Floating Mode placed near the app root, with initialIsOpen controlling default visibility.

Key Takeaways

1. Import TanStackRouterDevtools for automatic prod-exclusion; use TanStackRouterDevtoolsInProd only when devtools are intentionally needed in production.
2. Devtools options like position, panelProps, shadowDOMTarget, and containerElement allow fine control over placement and styling without forking the component.
3. Use TanStackRouterDevtoolsPanel (Fixed/Embedded modes) when the floating toggle UX is not desired, e.g. to embed devtools inside a custom debug layout.

Connects To

• Ch 2: Quick Start scaffolds a project where devtools can immediately be added to the root route.
• Ch 7: Manual Installation covers where the root route file lives when set up by hand.