web-source-inspect README

The project's README from github.com/shaojie-li/web-source-inspect. As one markdown file: README.md.

React Trace

An experimental, zero-integration Chrome extension that maps an element in a React development page back to the JSX/TSX source that created it, then opens that location in VS Code or Cursor.

React Trace demo

No project-code changes required. Load the extension in Chrome; do not add a package, a Babel/Vite plugin, or application instrumentation. React Trace reads the React runtime and source maps already available in your development page.

Experimental. React Trace relies on React development-only internals and accessible source maps. It is intended for local development, not production pages.

Why

When inspecting a React UI, browser DevTools can show the DOM and styles but not always the source line that created an element. React Trace shortens that loop without modifying the project being inspected:

  1. Hold Alt and point at an element.
  2. See its source location and React component chain.
  3. Pin the result with Alt + click.
  4. Open the exact JSX/TSX location in your editor.

Features

Quick start

1. Load the extension

  1. Open chrome://extensions.
  2. Enable Developer mode.
  3. Choose Load unpacked and select this repository directory.
  4. Reload the extension and then reload the target page whenever extension code changes.

2. Run the included demo

pnpm --dir demo install
pnpm --dir demo dev

Open http://localhost:5173. The demo is only for verification; any supported local React development page works after loading the extension. The extension is injected only on http://localhost/* and http://127.0.0.1/*.

3. Configure the project root

For React 19, React Trace may need an absolute project root to turn a source-map path into a local file path. Click Settings in the result card, or open the extension options page, and map the page origin to the project directory:

http://localhost:5173 -> /absolute/path/to/source-inspect/demo

The setting is stored locally in Chrome. If the isolated-world bridge is unavailable, the extension falls back to page localStorage.

Usage

Gesture Result
Hold Alt and move the pointer Shows a blue outline and a live source-location hint.
Alt + click an element Pins an orange outline and opens a result card.
Click a blue location in the card Opens the file, line, and column in the selected editor.
Press Esc, click ×, or click outside the card Closes the pinned result.

The result card can show two different but useful concepts:

They can differ when a parent creates an element and passes it to a child as children or another prop.

Demo coverage

The demo exercises the cases that are easiest to get wrong:

  1. Simple elements in one file.
  2. List rendering across TodoCard.tsx and TodoItem.tsx.
  3. Nested memo and forwardRef components.
  4. DOM inserted with innerHTML, which has no Fiber and must fall back to a React ancestor.
  5. An element passed through a prop, where source location and Fiber ownership differ.
  6. A dropdown with a fullscreen mask that would otherwise steal event.target.

Supported environments and limitations

Area Current behavior
Browser Chrome 111+; the extension uses Manifest V3 world: "MAIN".
Hosts http://localhost/* and http://127.0.0.1/* only. HTTPS localhost, LAN IPs, and custom hosts are not injected.
React React development builds only. React 18.3.1 and 19.2.8 were verified.
Production builds Unsupported: React's debug source data is not available.
Source maps Required for the React 19 path; the served module and its map must be fetchable from the page.
Editors VS Code and Cursor. Other editors can be added to the EDITORS list in content.js.
Caching Parsed source maps are cached in memory without a size cap. HMR query strings can create duplicate cache entries.

How it works

React Trace uses a small two-script architecture because React Fiber expandos are visible only from the page's main world, while chrome.storage is available only from the extension's isolated world.

File Context Responsibility
content.js Main world Reads React Fiber data, resolves source maps, renders the overlay/card, and opens editors.
bridge.js Isolated world Proxies configuration reads and writes through chrome.storage.local.
options.html / options.js Extension page Manages the editor choice and origin-to-project-root mappings.

React 18 and React 19

React runtime Signal Resolution
React 18 fiber._debugSource Already contains a source file, line, and column.
React 19 fiber._debugStack Provides a generated JSX call site; React Trace parses the source map to recover the original source location.

For path inference, the extension prefers explicit paths over guesses: Vite /@fs/ URLs, compiler-injected fileName values, absolute sources, sourceRoot, then a configured project root combined with the module URL or normalized sources path. If it cannot infer a safe absolute path, it reports the failure instead of opening a guessed file.

Verification

Run the focused Node tests:

node test/path-infer.test.mjs
node test/placement.test.mjs

Build the React demo:

pnpm --dir demo build

To compare React runtime behavior without installing dependencies, start a local server from the repository root:

python3 -m http.server 5200

Then open React 19 or React 18.

Roadmap

Contributing

This is an early-stage prototype. When reporting an issue, include the React version, bundler and dev-server version, module URL, source-map shape, and the expected versus actual source location. Run the verification commands above before submitting a change.

License

Licensed under the Apache License 2.0.

web-source-inspect (shaojie-li/web-source-inspect)

Searching Database…

193 ·GitHub
Web-source-inspect
What is this?React Trace is an experimental Chrome extension that maps a React element on a page back to the JSX/TSX source that created it and opens that exact spot in VS Code or Cursor.
Is it a browser extension, or do I have to install something in my project?It is a pure browser extension: you add no packages, no Babel/Vite plugin, no source transforms, and no changes to your application code.
How do I get it into Chrome?Open chrome://extensions, enable Developer mode, then choose Load unpacked and select this repository directory.
What are the main limitations?Only React development builds work (18.3.1 and 19.2.8 verified), in Chrome 111+, and it injects on localhost pages only. Production builds are unsupported because React's debug source data is unavailable.
What's the difference between 'source location' and 'component chain' in the result card?Source location is the JSX expression that created the element; component chain is the element's ownership in the Fiber tree. They can differ when a parent creates an element and passes it to a child as children or another prop.
Does it handle tricky elements like portals or DOM injected outside React?Yes. It handles fullscreen masks and portals by inspecting elementsFromPoint() and capturing the Alt-click before page handlers run, and for DOM with no Fiber (e.g. inserted via innerHTML) it falls back to the nearest React ancestor.
What's on the roadmap?Moving large source-map parsing to a worker with a bounded cache, normalizing HMR module URLs before caching, and validating more bundlers and framework-specific inspection paths.
What are similar projects?redux-devtools-extension, react-devtools, devtools-v6, react-scan, chrome-extensions-samples, redux-devtools, pretty-ts-errors, cat-catch
Which topics is it in?developer-experience, jsx, extension, chrome, devtools, vscode, debugging, chrome-extension, browser-extension, cursor, utility, web-development
Creator
shaojie-li
Size
2.9 MB
Stars
193
Updated
CommitAug 12
Age
2mo
Commits · 90 Days