CauseScope

Click any UI. Trace the cause.

Select any element in your React app and follow it back to the exact TSX, the decision that produced it, and the state or response behind that decision.

Try the live lab · Documentation · 60-second setup · Beta testing · Roadmap · Discussions · 中文

<button disabled={!canRefund}>Refund order</button>
                     │
                     ├─ canRefund → false
                     ├─ order.status === "paid" → false
                     ├─ order.status = "pending"
                     └─ GET /api/orders/4821 · 200

React DevTools can tell you that canRefund is false. CauseScope tells you why it is false.

npm i -D causescope@beta

pnpm add -D causescope@beta
yarn add -D causescope@beta

// vite.config.ts
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";
import causeScope from "causescope/vite";

export default defineConfig({
  plugins: [react(), causeScope()],
});

Start the Vite development server, click Inspect, and select an element. Hold Option/Alt while clicking for a shortcut; while the drawer is open, select another page element directly. Keyboard users can focus Inspect, press Enter, focus a page element, and press Enter or Space; arrow keys navigate the inspector tabs and Escape closes it.

CauseScope only runs for vite serve in development. Production builds contain no instrumentation, overlay, editor endpoint, or debug attributes.

Testing before stable 1.0? Use the beta testing guide to exercise multiple evidence paths and share a sanitized minimal TypeScript reproduction.

A disabled button is one useful scenario, not the product model. CauseScope can select buttons, text, inputs, lists, and other DOM elements, and it reports the evidence that actually exists for that element. For static text or an element without a dynamic decision, it simply shows the exact source code and component location. Missing or ambiguous evidence is marked unavailable instead of being invented.

It also provides exact file, line, and column coordinates plus an editor-agnostic Open in editor action.

CauseScope complements existing developer tools instead of replacing them.

Install adapters before the first React render so initial cache and store values keep their provenance.

// main.tsx
if (import.meta.env.DEV) {
  const [{ getCauseScopeRuntime }, { reactQueryAdapter }, { zustandAdapter }] = await Promise.all([
    import("causescope"),
    import("causescope/adapters/react-query"),
    import("causescope/adapters/zustand"),
  ]);

  const runtime = getCauseScopeRuntime();
  runtime.installAdapter(reactQueryAdapter({ queryClient }));
  runtime.installAdapter(zustandAdapter({
    stores: { editorStore },
    sources: {
      editorStore: { file: "src/stores/editor.ts", line: 12, column: 28 },
    },
  }));
}

React Query provenance includes the query key, status, fetch status, and update time. Zustand stores are explicit by design; CauseScope never searches for unrelated stores.

CI installs the packed npm artifact into isolated Vite 5.4, 6.4, 7.3, and 8.1 consumers and performs a real TSX transform. examples/ adds React 18/19, Babel/SWC, multi-page, multi-component, multi-file, Portal, Suspense, Error Boundary, Fast Refresh, React Query, and Zustand browser scenarios.

Artifact growth is gated separately: the browser runtime graph, Vite plugin, optional adapters, publishable files, and npm tarball all have enforced performance budgets.

The five supported npm entrypoints and their complete declaration graph are protected by a reviewable public API snapshot.

CauseScope has no account, telemetry, remote service, or upload path. Network and storage tracing are development-only and independently configurable. It records only storage keys accessed during the current page run; it does not enumerate browser storage.

Authorization, cookie, API-key, token, password, and secret variants are redacted across headers, URLs, objects, the inspector, and exported traces. Recording is bounded to 10,000 trace nodes, 200 timeline events, 1 MB per response, and 20 MB total response data unless configured otherwise.

Read the privacy and threat model before using CauseScope with sensitive applications.

CauseScope uses pnpm Workspace + Turborepo.

pnpm install
pnpm check

The full gate runs type checking, unit tests, every build, production-absence and performance-budget scans, public API and release-policy checks, an isolated StackBlitz build, packed-package Vite 5–8 consumers, and Playwright end-to-end coverage.

Issues and pull requests are welcome. Start with the roadmap, contribution guide, support policy, security policy, and Code of Conduct. Use Discussions for questions and early ideas.

Released under the MIT License.