feat: add React Scan plugin for TanStack Devtools

.changeset/react-scan-devtools.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/react-scan-devtools': minor
+'@tanstack/devtools': patch
+---
+
+Add `@tanstack/react-scan-devtools`, a React Scan plugin for TanStack Devtools. The plugin starts `react-scan`, shows live render diagnostics, and hides the floating toolbar.

docs/config.json

@@ -206,6 +206,10 @@
             {
               "label": "a11y",
               "to": "framework/react/examples/a11y-devtools"
+            },
+            {
+              "label": "React Scan",
+              "to": "plugins/react-scan"
             }
           ]
         },

docs/plugins/react-scan.md

@@ -0,0 +1,86 @@
+---
+title: React Scan Plugin
+id: react-scan-plugin
+---
+
+You want the official [react-scan](https://github.com/aidenybai/react-scan) panel inside TanStack Devtools, not a second floating toolbar on the page. This plugin starts `scan()` in the app, so app re-renders are scanned. It then locks the native React Scan panel into the TanStack tab.
+
+That native panel includes:
+
+- Inspect mode to pick a component on the page
+- The inspector: What Changed, props, and the component tree
+- Slowdown notifications
+- Outline toggle for re-renders
+- FPS meter
+
+Page outlines stay on the page. The native panel fills the plugin pane. You cannot drag it and it has no close control. Close the tab from TanStack Devtools.
+
+## Installation
+
+```bash
+npm install @tanstack/react-scan-devtools react-scan
+# or
+pnpm add @tanstack/react-scan-devtools react-scan
+# or
+yarn add @tanstack/react-scan-devtools react-scan
+```
+
+## Quick Start
+
+```tsx
+import { createRoot } from 'react-dom/client'
+import { TanStackDevtools } from '@tanstack/react-devtools'
+import { reactScanDevtoolsPlugin } from '@tanstack/react-scan-devtools'
+
+createRoot(document.getElementById('root')!).render(
+  <>
+    <App />
+    <TanStackDevtools plugins={[reactScanDevtoolsPlugin()]} />
+  </>,
+)
+```
+
+`scan()` starts when you call `reactScanDevtoolsPlugin()`. You do not need a script tag.
+
+Do not also load `react-scan/dist/auto.global.js`. Two scanners will run at the same time.
+
+## How to use the tab
+
+1. Open the **React Scan** plugin.
+2. Click the inspect icon, then click a component in the app.
+3. The inspector shows why that component rendered and its tree.
+4. Interact with the app (for example click **Increment count**). What Changed updates for the selected component.
+5. Click the bell for slowdown notifications.
+6. Use the outline toggle to turn page outlines on or off.
+
+## Options
+
+```tsx
+reactScanDevtoolsPlugin({
+  enabled: true,
+  log: false,
+  animationSpeed: 'fast',
+  onRender: (fiber, renders) => {
+    // optional
+  },
+})
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Start scanning when the factory runs |
+| `log` | `false` | Log renders to the console |
+| `animationSpeed` | `'fast'` | Outline animation speed |
+| `onRender` | none | Called for each render batch |
+
+If you call the factory twice, `scan()` still runs once. The first `onRender` you pass is the one that stays.
+
+## Production
+
+The root import is a no-op when `process.env.NODE_ENV` is not `'development'`. It does not call `scan()`.
+
+If you want the real plugin in every environment, import `@tanstack/react-scan-devtools/production`. That import tells `react-scan` to run even when React is a production build.
+
+## Example
+
+See `examples/react/basic`. Open the React Scan tab, click inspect, click **Increment count**, then click it again to see What Changed.

examples/react/basic/index.html

@@ -26,7 +26,6 @@
       content="A basic example of using TanStack Devtools with React and loading up the social previews"
     />
     <meta name="twitter:url" content="https://example.com/basic" />
-    <script src="https://unpkg.com/react-scan/dist/auto.global.js"></script>
     <title>Basic Example - TanStack Devtools</title>
     <meta
       name="description"

examples/react/basic/package.json

@@ -19,6 +19,7 @@
     "@tanstack/react-query-devtools": "^5.90.1",
     "@tanstack/react-router": "^1.132.0",
     "@tanstack/react-router-devtools": "^1.132.0",
+    "@tanstack/react-scan-devtools": "workspace:*",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "zod": "^4.3.5"

examples/react/basic/src/setup.tsx

@@ -11,6 +11,7 @@ import {
 } from '@tanstack/react-router'
 import { TanStackDevtools } from '@tanstack/react-devtools'
 import { a11yDevtoolsPlugin } from '@tanstack/devtools-a11y/react'
+import { reactScanDevtoolsPlugin } from '@tanstack/react-scan-devtools'
 import { A11yAuditFixture } from './a11y-audit-fixture'
 import { PackageJsonPanel } from './package-json-panel'
 
@@ -66,6 +67,7 @@ export default function DevtoolsExample() {
         }}
         config={{ sourceAction: 'copy-path', position: 'bottom-left' }}
         plugins={[
+          reactScanDevtoolsPlugin(),
           a11yDevtoolsPlugin(),
           {
             name: 'TanStack Query',

package.json

@@ -94,7 +94,8 @@
     "@tanstack/solid-devtools": "workspace:*",
     "@tanstack/devtools-vite": "workspace:*",
     "@tanstack/svelte-devtools": "workspace:*",
-    "@tanstack/angular-devtools": "workspace:*"
+    "@tanstack/angular-devtools": "workspace:*",
+    "@tanstack/react-scan-devtools": "workspace:*"
   },
   "files": [
     "skills",

packages/devtools/src/tabs/plugin-registry.ts

@@ -226,6 +226,25 @@ const PLUGIN_REGISTRY: Record<string, PluginMetadata> = {
     tags: ['TanStack', 'a11y'],
   },
 
+  // React Scan
+  '@tanstack/react-scan-devtools': {
+    packageName: '@tanstack/react-scan-devtools',
+    title: 'React Scan',
+    description:
+      'Find React render problems. Live render counts, unnecessary renders, and scan settings.',
+    pluginImport: {
+      importName: 'reactScanDevtoolsPlugin',
+      type: 'function',
+    },
+    pluginId: 'react-scan',
+    docsUrl: 'https://tanstack.com/devtools/latest/docs/plugins/react-scan',
+    repoUrl: 'https://github.com/aidenybai/react-scan',
+    author: 'TanStack',
+    framework: 'react',
+    isNew: true,
+    tags: ['React', 'performance', 'renders'],
+  },
+
   // TanStack AI
   '@tanstack/react-ai-devtools': {
     packageName: '@tanstack/react-ai-devtools',

packages/react-scan-devtools/CHANGELOG.md

@@ -0,0 +1 @@
+# @tanstack/react-scan-devtools

packages/react-scan-devtools/README.md

@@ -0,0 +1,15 @@
+# @tanstack/react-scan-devtools
+
+React Scan plugin for TanStack Devtools. It starts `react-scan` in the app and docks the official React Scan panel into the TanStack tab.
+
+```bash
+npm install @tanstack/react-scan-devtools react-scan
+```
+
+```tsx
+import { TanStackDevtools } from '@tanstack/react-devtools'
+import { reactScanDevtoolsPlugin } from '@tanstack/react-scan-devtools'
+;<TanStackDevtools plugins={[reactScanDevtoolsPlugin()]} />
+```
+
+Docs: https://tanstack.com/devtools/latest/docs/plugins/react-scan

packages/react-scan-devtools/eslint.config.js

@@ -0,0 +1,10 @@
+// @ts-check
+
+import rootConfig from '../../eslint.config.js'
+
+export default [
+  ...rootConfig,
+  {
+    rules: {},
+  },
+]

packages/react-scan-devtools/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@tanstack/react-scan-devtools",
+  "version": "0.0.1",
+  "description": "React Scan plugin for TanStack Devtools",
+  "author": "TanStack",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/devtools.git",
+    "directory": "packages/react-scan-devtools"
+  },
+  "homepage": "https://tanstack.com/devtools",
+  "bugs": {
+    "url": "https://github.com/TanStack/devtools/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "keywords": [
+    "devtools",
+    "react",
+    "react-scan",
+    "performance",
+    "renders"
+  ],
+  "type": "module",
+  "types": "dist/esm/index.d.ts",
+  "module": "dist/esm/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      }
+    },
+    "./production": {
+      "import": {
+        "types": "./dist/esm/production.d.ts",
+        "default": "./dist/esm/production.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "test:build": "publint --strict",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@tanstack/devtools-utils": "workspace:^",
+    "react-scan": "^0.5.7"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "peerDependencies": {
+    "@types/react": ">=17.0.0",
+    "@types/react-dom": ">=17.0.0",
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    },
+    "@types/react-dom": {
+      "optional": true
+    }
+  }
+}

packages/react-scan-devtools/src/core/components/Shell.tsx

@@ -0,0 +1,32 @@
+import { useEffect, useRef } from 'react'
+import { dockReactScanToolbar } from '../host-toolbar'
+
+export function ReactScanDevtoolsPanel() {
+  const hostRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const host = hostRef.current
+    if (!host) {
+      return
+    }
+    return dockReactScanToolbar(host)
+  }, [])
+
+  return (
+    <div
+      ref={hostRef}
+      data-tsd-surface
+      data-testid="react-scan-host"
+      style={{
+        position: 'relative',
+        height: '100%',
+        width: '100%',
+        minHeight: '100%',
+      }}
+    />
+  )
+}
+
+export function ReactScanDevtoolsPanelNoOp() {
+  return null
+}