Skip to content
Source
Sign inSign up
TanStack/devtools
Open History to see the last commit

source-inspector.md

105 lines3.5 KB

1---
2title: Source Inspector
3id: source-inspector
4---
5​
6The source inspector lets you click any element in your app to open its source file in your editor. When activated, the devtools overlay highlights elements as you hover over them and shows their source file location. Click to open the file at the exact line.
7​
8## Requirements
9​
10Two things are needed for the source inspector to work:
11​
12- The `@tanstack/devtools-vite` plugin must be installed and running (dev server only)
13- Source injection must be enabled: `injectSource.enabled: true` (this is the default)
14​
15The feature only works in development. In production builds, source attributes are not injected.
16​
17## How It Works
18​
19```mermaid
20flowchart LR
21 A["Your JSX/TSX files"] -- "AST transform" --> B["data-tsd-source<br/>attributes injected"]
22 B -- "Hold inspect hotkey<br/>+ click element" --> C["Devtools reads<br/>data-tsd-source"]
23 C -- "HTTP request" --> D["Vite dev server"]
24 D -- "launch-editor" --> E["Opens file in editor<br/>at exact line"]
25```
26​
27The Vite plugin uses oxc-parser to parse your JSX/TSX files during development. It adds a `data-tsd-source="filepath:line:column"` attribute to every JSX element via MagicString. When you activate the source inspector and click an element, the devtools reads this attribute and sends a request to the Vite dev server. The server then launches your editor at the specified file and line using `launch-editor`.
28​
29## Activating the Inspector
30​
31There are two ways to activate the source inspector:
32​
33- **Hotkey**: Hold Shift+Alt+Ctrl (or Shift+Alt+Meta on Mac) β€” this is the default `inspectHotkey`. While held, the inspector overlay appears.
34- **Settings panel**: The inspect hotkey can be customized in the devtools Settings tab.
35​
36The hotkey can also be configured programmatically:
37​
38```ts
39<TanStackDevtools
40 config={{
41 inspectHotkey: ['Shift', 'Alt', 'CtrlOrMeta'],
42 }}
43/>
44```
45​
46## Ignoring Files and Components
47​
48Not all elements need source attributes. Use the `ignore` config to exclude files or components:
49​
50```ts
51import { devtools } from '@tanstack/devtools-vite'
52​
53export default {
54 plugins: [
55 devtools({
56 injectSource: {
57 enabled: true,
58 ignore: {
59 files: ['node_modules', /.*\.test\.(js|ts|jsx|tsx)$/],
60 components: ['InternalComponent', /.*Provider$/],
61 },
62 },
63 }),
64 ],
66```
67​
68Both `files` and `components` accept arrays of strings (exact match) or RegExp patterns.
69​
70## Click Action
71​
72By default, clicking an inspected element opens the file in your editor. You can change this to copy the source path to the clipboard instead using the `sourceAction` setting:
73​
74```ts
75<TanStackDevtools
76 config={{
77 sourceAction: 'copy-path',
78 }}
79/>
80```
81​
82| Value | Behavior |
83| --- | --- |
84| `"ide-warp"` | Opens the file in your editor at the exact line (default) |
85| `"copy-path"` | Copies the `filepath:line:column` string to the clipboard |
86​
87This is useful in environments where the Vite dev server cannot reach your editor, or when you want to paste the path elsewhere.
88​
89## Editor Configuration
90​
91Most popular editors work out of the box via the `launch-editor` package. Supported editors include VS Code, WebStorm, Sublime Text, Atom, and more ([full list](https://github.com/yyx990803/launch-editor?tab=readme-ov-file#supported-editors)).
92​
93For unsupported editors, use the `editor` config:
94​
95```ts
96devtools({
97 editor: {
98 name: 'My Editor',
99 open: async (path, lineNumber, columnNumber) => {
100 const { exec } = await import('node:child_process')
101 exec(`myeditor --goto "${path}:${lineNumber}:${columnNumber}"`)
102 },
103 },
104})
105```