insightrecorder/docs
SDKs / React adapter

React adapter

Error boundaries swallow render errors before window.onerror ever sees them. This closes that gap and attaches the component stack.

Requires React 16.8+Package @insightrecorder/capture-reactSource on GitHub →

Before you start

Where your InsightRecorder runs
The base URL every call goes to — http://localhost:8080 when you are running it locally, your own hostname otherwise.
A capture token
Settings → Integrations. It goes in your page source and is public by design, like an error-tracker DSN: it permits submitting a capture and nothing else. Do not reuse a server API key here.
  1. 01

    Install

    The browser agent must already be on the page — this adapter talks to it, it does not replace it.

    npm install @insightrecorder/capture-react
  2. 02

    Wrap the tree

    One boundary at the root, and more around any subtree that should fail on its own — a boundary only catches errors from below it.

    import { CaptureErrorBoundary } from "@insightrecorder/capture-react";

createRoot(el).render(
  <CaptureErrorBoundary fallback={<SomethingBroke />}>
    <App />
  </CaptureErrorBoundary>,
);
  3. 03

    Report from anywhere else

    An event handler, a mutation, an existing boundary you do not want to replace.

    import { reportReactError } from "@insightrecorder/capture-react";

reportReactError(error, { componentStack }, { severity: "P1" });
  4. 04

    Verify it is working

    Render a component that throws, inside the boundary. The agent alone would never see this — the boundary intercepts it first, which is the whole reason this adapter exists.

    function Boom() {
  throw new Error("insightrecorder smoke test");
}

// Inside <CaptureErrorBoundary>, temporarily:
<Boom />

    Then look for the line at /app/logs and the report at /app/bugs.

    If nothing shows up

    Fallback rendered but no bug filed? The browser agent's script tag is missing, or loads after the app — the adapter reports through window.insightRecorder, so the agent has to be on the page already.

Before you ship

  • — Props and state are never captured — they routinely hold tokens and personal data.
  • — A missing agent is a no-op, never a crash: telemetry must not break the page it watches.
  • — React Router navigations already appear as steps; the agent patches the history API.
PROMPT Install the React adapter SDK with an AI agent
Raw .md

Paste this into a coding agent running inside your project, or point the agent at /docs/prompts/react directly. It is self-contained: the agent needs no prior knowledge of InsightRecorder.

# Install and wire the InsightRecorder React adapter

Paste this into a coding agent (Claude Code, Cursor, …) running inside your
React application's repository. It is self-contained — the agent needs no prior
knowledge of InsightRecorder.

---

You are working in a React application. Wire it to InsightRecorder so a crash files a
bug report with the console, network and click timeline that led to it.

**Context you need:**

- InsightRecorder's browser agent (`capture.js`) records console output, network
  calls and user steps in memory and transmits nothing until a report is
  triggered. It is loaded with a `<script>` tag and a public capture token.
- The agent alone is not enough for React: **error boundaries swallow render
  errors**, so `componentDidCatch` runs and `window.onerror` never fires. The
  `@insightrecorder/capture-react` package bridges that and attaches the component
  stack.
- The capture token is public by design, like an error-tracker DSN. It is
  **not** an API key and carries no scopes. Find it in the InsightRecorder UI under
  *Settings → Integrations*.

**Steps:**

1. Add the agent script to the HTML document that boots the app —
   `index.html`, or the framework's document template (`app/root.tsx` for Remix,
   `app/layout.tsx` for Next.js):

   ```html
   <script src="https://<insightrecorder-host>/static/js/capture.js"
           data-token="<capture token>"></script>
   ```

   Read the host and token from the project's existing environment mechanism
   (`import.meta.env`, `process.env`, a config file) rather than hard-coding
   them. If either is missing, the tag must be omitted and the app must run
   normally — telemetry is never a boot dependency.

2. Install the adapter: `npm install @insightrecorder/capture-react` (or the yarn/pnpm
   equivalent this project uses).

3. Wrap the tree at the root, **inside** any provider the fallback needs (theme,
   i18n) but outside the routes:

   ```jsx
   import { CaptureErrorBoundary } from "@insightrecorder/capture-react";

   <CaptureErrorBoundary fallback={<SomethingBroke />}>
     <App />
   </CaptureErrorBoundary>
   ```

   If the project already has an error boundary, do **not** add a second one
   around the same subtree — call `reportReactError(error, info)` from the
   existing boundary's `componentDidCatch` instead.

4. Add boundaries around subtrees that should fail independently — a dashboard
   widget, an embedded editor — so one broken panel does not blank the page.
   Only do this where the project's layout makes it meaningful.

5. If the app uses hash routing or a memory router, call
   `captureNavigation(path)` on route change. With a normal history router,
   skip this: the agent already patches `history.pushState`.

**Rules — do not violate these:**

- Do **not** capture props, state, form values, headers, cookies or request
  bodies in any report you write. They routinely carry credentials and personal
  data, and the SDK deliberately never reads them.
- Do **not** put the capture token in a server-side secret store or an API-key
  variable — it belongs in the page, and treating it as a secret will just make
  the wiring wrong.
- Do **not** make the app's boot depend on the agent loading. Every adapter
  entry point is already a no-op when the agent is absent; keep it that way.
- Do **not** replace the project's existing error reporting (Sentry, etc.)
  unless you were asked to. Both can run.

**Verify before you finish:**

1. The project's build and test commands pass.
2. Run the app, throw a deliberate error inside a component's render, and
   confirm a bug appears in InsightRecorder at `/app/bugs` with the component stack.
3. Open that bug and confirm the console and network timeline are populated.
4. Confirm the app still boots with the script tag removed.
5. Report what you changed and where each boundary was placed.

If anything is ambiguous — which HTML template boots the app, whether a boundary
already exists — inspect the repository and follow what is already there. Do not
restructure the application to fit the SDK.