TanStack · ardeora · Sep 2, 2024 · Jul 4, 2024 · Aug 29, 2024 · Sep 2, 2024
diff --git a/docs/config.json b/docs/config.json
@@ -929,6 +929,10 @@
             {
               "label": "Shadow DOM",
               "to": "framework/react/examples/shadow-dom"
+            },
+            {
+              "label": "Devtools Embedded Panel",
+              "to": "framework/react/examples/devtools-panel"
             }
           ]
         },

diff --git a/docs/framework/react/devtools.md b/docs/framework/react/devtools.md
@@ -83,7 +83,50 @@ function App() {
   - The position of the React Query devtools panel
 - `client?: QueryClient`,
   - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.
-- `errorTypes?: { name: string; initializer: (query: Query) => TError}`
+- `errorTypes?: { name: string; initializer: (query: Query) => TError}[]`
+  - Use this to predefine some errors that can be triggered on your queries. Initializer will be called (with the specific query) when that error is toggled on from the UI. It must return an Error.
+- `styleNonce?: string`
+  - Use this to pass a nonce to the style tag that is added to the document head. This is useful if you are using a Content Security Policy (CSP) nonce to allow inline styles.
+- `shadowDOMTarget?: ShadowRoot`
+  - Default behavior will apply the devtool's styles to the head tag within the DOM.
+  - Use this to pass a shadow DOM target to the devtools so that the styles will be applied within the shadow DOM instead of within the head tag in the light DOM.
+
+## Embedded Mode
+
+Embedded mode will show the development tools as a fixed element in your application, so you can use our panel in your own development tools.
+
+Place the following code as high in your React app as you can. The closer it is to the root of the page, the better it will work!
+
+```tsx
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+
+function App() {
+  const [isOpen, setIsOpen] = React.useState(false)
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      {/* The rest of your application */}
+      <button
+        onClick={() => setIsOpen(!isOpen)}
+      >{`${isOpen ? 'Close' : 'Open'} the devtools panel`}</button>
+      {isOpen && <ReactQueryDevtoolsPanel onClose={() => setIsOpen(false)} />}
+    </QueryClientProvider>
+  )
+}
+```
+
+### Options
+
+- `style?: React.CSSProperties`
+  - Custom styles for the devtools panel
+  - Default: `{ height: '500px' }`
+  - Example: `{ height: '100%' }`
+  - Example: `{ height: '100%', width: '100%' }`
+- `onClose?: () => unknown`
+  - Callback function that is called when the devtools panel is closed
+- `client?: QueryClient`,
+  - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.
+- `errorTypes?: { name: string; initializer: (query: Query) => TError}[]`
   - Use this to predefine some errors that can be triggered on your queries. Initializer will be called (with the specific query) when that error is toggled on from the UI. It must return an Error.
 - `styleNonce?: string`
   - Use this to pass a nonce to the style tag that is added to the document head. This is useful if you are using a Content Security Policy (CSP) nonce to allow inline styles.

diff --git a/examples/react/devtools-panel/.eslintrc b/examples/react/devtools-panel/.eslintrc
@@ -0,0 +1,3 @@
+{
+  "extends": ["plugin:react/jsx-runtime", "plugin:react-hooks/recommended"]
+}
diff --git a/examples/react/devtools-panel/.gitignore b/examples/react/devtools-panel/.gitignore
@@ -0,0 +1,27 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+pnpm-lock.yaml
+yarn.lock
+package-lock.json
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/examples/react/devtools-panel/README.md b/examples/react/devtools-panel/README.md
@@ -0,0 +1,6 @@
+# Example
+
+To run this example:
+
+- `npm install`
+- `npm run dev`
diff --git a/examples/react/devtools-panel/index.html b/examples/react/devtools-panel/index.html
@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="icon" type="image/svg+xml" href="/emblem-light.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#000000" />
+
+    <title>TanStack Query React Devtools Panel Example App</title>
+  </head>
+  <body>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>
diff --git a/examples/react/devtools-panel/package.json b/examples/react/devtools-panel/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "@tanstack/query-example-react-devtools-panel",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.53.2",
+    "@tanstack/react-query-devtools": "^5.53.2",
+    "react": "19.0.0-rc-4c2e457c7c-20240522",
+    "react-dom": "19.0.0-rc-4c2e457c7c-20240522"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.1",
+    "typescript": "5.3.3",
+    "vite": "^5.3.5"
+  }
+}
diff --git a/examples/react/devtools-panel/public/emblem-light.svg b/examples/react/devtools-panel/public/emblem-light.svg
diff --git a/examples/react/devtools-panel/src/index.tsx b/examples/react/devtools-panel/src/index.tsx
@@ -0,0 +1,58 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import {
+  QueryClient,
+  QueryClientProvider,
+  useQuery,
+} from '@tanstack/react-query'
+import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
+
+const queryClient = new QueryClient()
+
+export default function App() {
+  const [isOpen, setIsOpen] = React.useState(false)
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Example />
+      <button
+        onClick={() => setIsOpen(!isOpen)}
+      >{`${isOpen ? 'Close' : 'Open'} the devtools panel`}</button>
+      {isOpen && <ReactQueryDevtoolsPanel onClose={() => setIsOpen(false)} />}
+    </QueryClientProvider>
+  )
+}
+
+function Example() {
+  const { isPending, error, data, isFetching } = useQuery({
+    queryKey: ['repoData'],
+    queryFn: async () => {
+      const response = await fetch(
+        'https://api.github.com/repos/TanStack/query',
+      )
+      return await response.json()
+    },
+  })
+
+  if (isPending) return 'Loading...'
+
+  if (error) return 'An error has occurred: ' + error.message
+
+  return (
+    <div
+      style={{
+        paddingBottom: 20,
+      }}
+    >
+      <h1>{data.full_name}</h1>
+      <p>{data.description}</p>
+      <strong>👀 {data.subscribers_count}</strong>{' '}
+      <strong>✨ {data.stargazers_count}</strong>{' '}
+      <strong>🍴 {data.forks_count}</strong>
+      <div>{isFetching ? 'Updating...' : ''}</div>
+    </div>
+  )
+}
+
+const rootElement = document.getElementById('root') as HTMLElement
+ReactDOM.createRoot(rootElement).render(<App />)
diff --git a/examples/react/devtools-panel/tsconfig.json b/examples/react/devtools-panel/tsconfig.json
@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src", "eslint.config.js"]
+}
diff --git a/examples/react/devtools-panel/vite.config.ts b/examples/react/devtools-panel/vite.config.ts
@@ -0,0 +1,6 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+})