React quickstart
Everything the browser SDK reports, plus React render errors, error boundaries, and the route template of the page each error happened on.
Set up with an AI agent
Using a coding agent such as Claude Code, Codex or Cursor? Paste this prompt into it from the root of your project. It installs and configures the SDK for you, and leaves the API key for you to add.
Run `curl -fsSL https://vigilon.io/agents/install.md` and follow the instructions in that file to set up Vigilon in this project.Install the SDK
Install @vigilon/react only. It includes @vigilon/browser at the matching version and re-exports its API. It needs React 18 or later; reporting render errors through the root error handlers needs React 19.
npm install @vigilon/react
Create an API key of kind Browser on the API Keys tab of your project's Settings page, and list your app's origins under Allowed origins. The Browser quickstart explains both.
Start the SDK
Call init in a module of its own:
import { init } from "@vigilon/react";
init({
apiKey: "[YOUR_API_KEY]",
appName: "dashboard",
environment: "production",
appVersion: "2026.11.05-1",
});
Import it first in your entry point, above every other import, then pass the root error handlers to createRoot (or hydrateRoot):
import "./instrument";
import { rootErrorHandlers } from "@vigilon/react";
import { createRoot } from "react-dom/client";
import { App } from "./App";
createRoot(document.getElementById("root")!, rootErrorHandlers()).render(<App />);
Imports run in order, before the importing module's own code. Called in main.tsx itself, init would run only after everything App imports had loaded: an error thrown while those modules load would be missed, and so would the route of the first page if your router is tracked at module level.
React 19 reports render errors through these root options rather than the window error event. Without them Vigilon does not see errors that no error boundary catches, errors that a boundary catches (your router's included), or errors React recovers from, such as hydration mismatches.
Each handler reports the error, then calls your own callback for that option if you pass one, or logs the error as React would:
createRoot(
container,
rootErrorHandlers({
onCaughtError: (error, errorInfo) => logger.warn(error, errorInfo.componentStack),
}),
);
React 18 has only onRecoverableError. Wrap a React 18 app in an ErrorBoundary to report its render errors.
Add error boundaries
ErrorBoundary reports errors thrown while rendering its children, with their component stack, and renders fallback in their place:
import { ErrorBoundary } from "@vigilon/react";
<ErrorBoundary
fallback={({ resetError }) => (
<div role="alert">
<p>Something went wrong.</p>
<button onClick={resetError}>Try again</button>
</div>
)}
>
<Invoices />
</ErrorBoundary>;
fallback is a node, or a function that receives error, componentStack, eventId, and resetError. onError is called once the error is reported, and onReset when resetError clears the boundary. An error is reported once, even when both a boundary and the root handlers see it.
Track route templates
Vigilon groups an error's affected pages by route template, such as /users/:id. With TanStack Router, track the router once after creating it:
import { trackTanStackRouter } from "@vigilon/react/tanstack-router";
const router = createRouter({ routeTree });
trackTanStackRouter(router);
With React Router 6.4 or later, using a data router:
import { trackReactRouter } from "@vigilon/react/react-router";
const router = createBrowserRouter(routes);
trackReactRouter(router);
Track the router only after init has run. Each tracker records the current page's template as soon as it is called; called before init, that is lost, and errors on the first page carry a page derived from the URL instead. With instrument.ts imported first, a router created and tracked at module level is fine.
Both return a function that stops tracking. A loader or action error in React Router renders the route's errorElement without reaching React's error handlers, so trackReactRouter reports it. Of the error responses a loader or action throws, only server errors (status 500 and above) are reported, without the response body; a 404 is treated as control flow.
With another router, call setRoute("/users/:id") on each navigation. Without a template, Vigilon derives the page from the URL path, replacing segments that look like IDs.
Check that errors arrive
Serve your app from one of the key's allowed origins, then throw a test error from the browser's developer console:
setTimeout(() => {
throw new Error("Vigilon test error");
});
The setTimeout makes it an uncaught error of the page, which the SDK reports. Browsers do not pass an error thrown directly at the console prompt to the page.
Open the project in Vigilon. The error appears on the Errors page, usually within a minute, as an error group with origin browser. Its sample shows the stack trace and the breadcrumbs recorded before the error.
Add debug: true to init to log what the SDK does. In the browser's network panel, a request to /v1/browser/events answered with HTTP 403 carries the reason in its response: a server key used instead of a browser key, or a page origin missing from the key's allowed origins. The SDK does not retry a 403.