Microsoft react-sourcetrace: Map Any DOM Element Back to Its React JSX Source

Microsoft has published react-sourcetrace, a small developer tool that answers a question every React debugger eventually asks: which line of JSX produced this element on the page? The README describes it as a way to "find the original JSX source and component ancestry of a React DOM element." It is MIT-licensed, supports React 18.3.x and 19.x, and ships adapters for Vite, TypeScript, Webpack and Rspack, plus Playwright helpers for tests.

The repository is brand new, with a handful of commits and no stars when we looked, so this is a release to understand rather than a trending favorite. It is worth a look because the same capability that helps a human debug a page also helps automated tools and coding agents connect what they see in the browser to the code they must edit.

react-sourcetrace at a glance

The problem it solves

In a React app, the DOM shows you <button class="btn">, but not which component rendered it or where in your source that JSX lives. Two buttons rendered by the same component share an implementation location, yet appear in different places in the tree. React DevTools can show component trees, but it is a browser extension aimed at humans, and the mapping from a DOM node to an exact file, line and column is not something your tests or scripts can easily read.

react-sourcetrace's README makes the distinction explicit: two buttons from the same component "retain the same implementation location but different instantiation paths." The tool records both, so you can tell not just where the JSX is written but which parent chain created that instance.

How it works

The build adapter wraps each JSX element as recordElement(<jsx />, location). Your project's own JSX transform, factory and pragmas still create the element; the runtime merely associates locations with elements and their props without changing either. In the browser, a runtime reads committed React trees and carries ancestry downward, including through reused children, portals, lazy boundaries and Suspense.

By default each traced element, SVG included, gets a non-enumerable, configurable element.__sourceTrace property holding the structured trace. HTML is not modified. A trace looks like this:

{
  "source": { "file": "src/Button.tsx", "line": 8, "column": 3, "name": "button" },
  "stack": [
    { "file": "src/Button.tsx", "line": 8, "column": 3, "name": "button" },
    { "file": "src/Toolbar.tsx", "line": 12, "column": 5, "name": "Button" }
  ],
  "coverage": "exact"
}

Paths are relative to the configured root, lines and columns are one-based, and frames run from the element toward the root, including React keys where available. If you prefer attributes, an alternate storage mode writes data-sourcetrace-src, data-sourcetrace-stack and data-sourcetrace-coverage onto elements instead.

Setup for a Vite project

Install it as a dev dependency with pnpm add -D react-sourcetrace. The adapters parse JSX with the project's own typescript package, with a peer range of 5.4 up to but not including 7. For Vite, the plugin must come before the React plugin:

import { sourceTrace } from "react-sourcetrace/vite";

export default defineConfig({
  plugins: [
    sourceTrace({
      root: fileURLToPath(new URL(".", import.meta.url)),
      enabled: process.env.SOURCETRACE_BUILD === "1",
    }),
    react(),
  ],
});

Two opt-ins are required. Build instrumentation defaults off and is switched on with SOURCETRACE_BUILD=1. Runtime tracing is switched on by opening the app with ?sourcetrace=1 or by setting window.__SOURCETRACE_ENABLED__ = true before application modules load. Then read a trace with window.__SOURCETRACE__?.inspect(element).

For Webpack, Rspack or SWC pipelines, run the react-sourcetrace/loader on original JSX before other source transforms with enforce: "pre". For TypeScript emit pipelines, use createSourceTraceTransformers and pass it through ts-loader's getCustomTransformers. Use either the loader or the TypeScript adapter, not both on the same source.

Playwright and test tooling

The package includes Playwright helpers. Call enableSourceTrace(page) before navigation, then readSourceTrace(locator) to get a trace for a located element, in either storage mode. The README notes that accessibility collectors can read element.__sourceTrace directly and serialize the full trace separately from HTML snapshots.

That makes a concrete workflow possible: a failing end-to-end test or an accessibility scan can report not just "this button has no label" but "this button, rendered at src/Toolbar.tsx line 12 inside Button, has no label."

Why this matters for coding agents

The README does not mention AI agents, so this section is our reading, not Microsoft's claim. Coding agents that drive a browser, such as in the tools we covered in Voyager, a creative agent harness, face a recurring gap: they can see a rendered element but must guess which file to edit. A machine-readable trace closes that gap. An agent could click an element in a running app, read its trace, and open the exact file and line, instead of grepping for a class name that appears in twenty components.

That is useful for loop engineering with coding agents, where a loop inspects the page, locates the code, edits, and re-checks. It could also be wrapped as an MCP server or packaged as a reusable agent skill. Nothing like that ships in the repository today, so treat it as a plausible integration, not an existing feature. For general Claude Code workflows, see the Claude Code commands reference.

What developers will ask first

How is this different from React DevTools? DevTools is an interactive inspector for a person. react-sourcetrace exposes a structured trace through a page API and a Playwright helper, so scripts, tests and agents can read the same information without a human clicking in an extension.

How is it different from source maps? Source maps translate compiled code positions back to original files for stack traces. They do not tell you which JSX instance produced a given DOM node or which component chain instantiated it. Here the trace is attached to the element, not to an error.

Will it slow my app? The README says enabled passes scan the document and committed roots and calls it diagnostic tooling, so keep it out of performance-sensitive production builds. With build instrumentation off, an uninstrumented build contains no tracing runtime or source metadata.

Does it change my markup or props? No. In the default property mode HTML is not modified and refreshes generate no DOM mutation records. The runtime associates locations with elements and props without altering either.

What does a worked example look like? Suppose an accessibility scan flags an unlabeled icon button. With tracing on, the test calls readSourceTrace(page.getByRole("button", { name: "Send" })). The returned source points at src/Button.tsx line 8, and the stack shows it was instantiated from src/Toolbar.tsx line 12. The fix goes in the toolbar's usage, not the shared button, and the trace tells you which.

Limits and gotchas from the README

The authors list their limitations in detail, which is a good sign for a young tool.

• Fiber is private. React Fiber access is read-only and version-gated to stable 18.3.x and 19.x, and the browser matrix does not cover every patch or feature.
• Ancestry, not a call stack. The stack is committed component and render ancestry. Ordinary helper calls are not frames.
• Only your source. Only original .tsx and .jsx files under the configured root are instrumented. Precompiled dependencies and manual element creation do not get invented locations.
• Ancestor-only coverage. When only ancestors are known, source is null and coverage is ancestor-only. Elements recreated with cloneElement, such as asChild slot patterns, are ancestor-only, with their authored call site in the stack.
• No SSR. Server HTML is not annotated, and SSR and hydration are not covered by the browser matrix. Discovery covers the current document, not arbitrary shadow roots.
• Staleness. A commit that changes no DOM can leave properties stale until the next flush, though inspect(element) is always current.
• Memo and fragments. If a current call site cannot be recovered, the frame is omitted rather than guessed.
• Performance. Enabled passes scan the document and committed roots; this is diagnostic tooling, not a production performance guarantee.

Security and privacy notes

The default property storage keeps tracing data out of HTML, and the property is "private by convention, not a security boundary." More important for production teams: source locations in shipped bundles remain inspectable even when runtime tracing is disabled, if you built with instrumentation. Keep SOURCETRACE_BUILD unset for public builds, and check that file paths in your traces do not reveal internal repository structure you would rather not expose.

Should you try it?

• Yes, if you maintain a React 18 or 19 app with Vite or Webpack and write Playwright tests or accessibility checks, and want failures to point at source.
• Maybe, if you are building agent tooling that edits front-end code and need a reliable element-to-file mapping.
• Not yet, if you depend on SSR or hydration coverage, or need a stable, widely tested package. The repository is new, with few commits and no community track record, and the README's publishing section says the maintainers had not yet bootstrapped the first npm publication, so check that the package is actually published before planning around pnpm add.

Related reading

• Voyager creative agent harness
• Loop engineering for coding agents
• What is MCP? The Model Context Protocol guide
• What are agent skills? Complete guide
• Claude Code commands reference
• Anthropic OSS Scanner
• Official: microsoft/react-sourcetrace on GitHub and React documentation

Details are from the repository README as of October 22, 2026 and may change as the project develops.