Why is a refund button disabled? The first line you find often looks complete while explaining almost nothing:
tsx<button disabled={!canRefund}>Refund order</button>
disabled is the symptom, not the answer. You still need to find where canRefund came from, which state transition changed the order, whether that state originated in an API response, and which rendered component instance owns the value. In a large application, a variable search quickly becomes an investigation across components, files, and runtime tools.
I built CauseScope to shorten that path. Start with the UI that is actually wrong, then follow observed evidence back to source, conditions, state, and network data.
Try the StackBlitz live lab without changing your own application. The source and issue tracker are on GitHub, and the package is available on npm.
What is CauseScope?
CauseScope is a local evidence inspector for React applications running on Vite. Select an element to see its exact TSX location, live expression and condition results, relevant state updates, and any Fetch/XHR response that can be confirmed as an origin. Evidence that was not observed or cannot be correlated reliably is labeled unavailable instead of being turned into a plausible-looking story.
That last constraint matters. A debugging tool that presents an inference as a fact can lead you to the wrong file faster than no tool at all.
The hard part is not seeing false; it is finding why it became false
React DevTools is excellent at component trees, Props, and Hooks. The browser Network panel is the authoritative place to inspect requests. But those facts live in separate views, and the developer still has to establish the relationship between them.
In the refund example, CauseScope does not stop at “canRefund = false.” It exposes a path you can check against the application:
text<button disabled={!canRefund}>Refund order</button> │ ├─ canRefund → false ├─ order.status === "paid" → false ├─ order.status = "pending" └─ GET /api/orders/4821 · 200
The point is not to replace reading code. It is to give that reading the correct starting point. You can see which expression produced the render result, which branch blocked the action, where the latest real setter or reducer transition was observed, and which response field is connected to the current value.
A disabled button is one scenario, not the product model
Disabled controls make a clear demo because the causal question is obvious. CauseScope does not force every selected element into a disabled template.
Select ordinary text with no dynamic decision and the inspector shows its source snippet, component, file, line, and column. Select an input, list item, or link and it reports only the evidence that exists for that element. If there is no state transition or network origin, the drawer does not fill the space with undefined rows or invent a setter, request, or blocking branch.
The inspector currently organizes evidence into five views:
| View | Question it answers |
|---|---|
| Why | Which TSX produced this UI, and what were the expression operands and condition branches? |
| Values | What are the current Props and Hook state for this component instance? |
| State | Where did the initial value and latest real setter or reducer transition occur? |
| Network | Which Fetch/XHR response and field can be confirmed as an origin? |
| Timeline | How did a DOM event, handler, update, render, and expression change unfold? |
It also reports exact file, line, and column coordinates with an editor-independent Open in editor action. While the drawer is open, you can select another page element directly instead of exiting and restarting inspection.
How does it avoid assembling a cause that merely looks convincing?
CauseScope separates evidence collection across several explicit boundaries. During the development server, the Vite plugin runs a Babel transform that adds stable source metadata to project-owned TSX nodes and wraps expressions that need observation. The transform must preserve evaluation counts and JavaScript short-circuit behavior; a debugger cannot be allowed to change the semantics it is trying to explain.
In the browser, the core runtime records bounded events and values, then correlates them with state updates, DOM events, stores, network responses, and storage access. React Fiber access is isolated in a dedicated adapter with separate React 18 and 19 layouts. The inspector itself uses Preact inside Shadow DOM, so application styles do not silently rewrite the debugging interface.
This architecture does not make every origin knowable. It gives confirmed, ambiguous, and unavailable evidence different outcomes instead. A separate production gate scans built output for runtime and instrumentation markers so development tooling cannot quietly remain in a release bundle.
How do you add CauseScope to React and Vite?
The supported range today is React 18/19 on Vite 5–8, using either the Babel or SWC version of the official React plugin.
- Install the development dependency:
bashnpm i -D causescope@beta
- Add the plugin to
vite.config.ts:
tsimport react from "@vitejs/plugin-react" import { defineConfig } from "vite" import causeScope from "causescope/vite" export default defineConfig({ plugins: [react(), causeScope()], })
- Start the same Vite development server you already use, choose Inspect, and select an element. Holding
Option/Altwhile clicking starts inspection immediately.
Explicit adapters are available for React Query and Zustand. The application installs them intentionally; CauseScope does not crawl unrelated stores and guess which one owns a value.
Why local-first and development-only are product requirements
Tracing Props, state, and responses means a tool may encounter sensitive development data. Its trust boundary therefore has to be an enforced part of the implementation, not a line in the launch copy.
CauseScope has no account, telemetry, cloud service, or upload path. It runs only during vite serve; production builds should contain no runtime, drawer, editor endpoint, or debug attributes. Network and storage observation can be disabled independently, and default recording is bounded by event counts and response sizes.
Built-in redaction covers common authorization, cookie, API-key, token, password, and secret variants in the inspector and exported traces. No automatic list can understand every domain-specific field, so teams should add their own rules and review every trace before sharing it. The complete contract is documented in the privacy and threat model.
The current boundary: Vite-first, not Next.js support
CauseScope is explicitly Vite-first today. React 18/19 with Vite 5–8 is the supported surface; Next.js is not supported yet.
The feasibility conclusion is public in the roadmap. A bounded integration for Client Components appears technically plausible. React Server Components are a harder boundary: they do not expose browser DOM nodes or client Fiber state, and server-side request execution is outside the current browser evidence model.
The project will not claim Next.js support until public fixtures and automated gates prove exact source coordinates, Turbopack and webpack consistency, production removal, honest RSC fallbacks, and acceptable interaction performance. This narrows the audience today, but it is better than letting someone discover a hidden framework limit halfway through setup.
What problems is it designed to solve?
CauseScope is most useful when the visual symptom is specific but its cause spans several layers:
- Why is this action unavailable, and which condition blocks it?
- Why did a status message remain on the wrong branch?
- Did the current value come from Props, local state, a store, or a response?
- A setter ran, so why does this component instance still show an older value?
- What was the order of the handler, update, render, and expression change after a click?
It is not meant to replace React DevTools, the Network panel, performance profiling, or a source debugger. It supplies the connective step they often leave to the developer: from the UI you are looking at to a reviewable evidence path.
Why I open-sourced it
Frontend debugging tools are usually organized around the data a tool owns: components in one panel, requests in another, source somewhere else. Developers arrive with a different question: “Why is the thing in front of me like this?”
CauseScope changes the entry point to that question. It is still a beta, and what it needs most is not abstract approval but counterexamples from real project structures: a component located incorrectly, a missing state origin, a response correlation that cannot be justified, or an instrumentation path that makes interaction slower.
If you maintain a React + Vite application, start with the live lab and decide whether the evidence path solves a real problem before installing anything. If it fails, a sanitized minimal TypeScript reproduction is especially valuable. If the direction is useful, you can also star CauseScope on GitHub and help more React developers find it.