Browser quickstart
Report uncaught errors, unhandled promise rejections, and the errors you catch in your web app. They appear on your project's Errors page next to your backend errors, each with its stack trace and the steps that led to it.
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 the package in your web app. It has no dependencies, adds about 7 KB gzipped, and does nothing until you call init.
npm install @vigilon/browser
Using React or Next.js? Follow the React or Next.js quickstart instead. Their packages include this one and add what the framework needs.
Create a browser API key
Open your project's Settings page, then the API Keys tab, and create a key of kind Browser. A browser key ships in your JavaScript, so anyone who loads your page can read it. It can only send browser errors to this project: Vigilon refuses it for traces and metrics.
Under Allowed origins, list the origins your app is served from, one per line, such as https://app.example.com. https://*.example.com covers every subdomain of example.com. Vigilon then accepts errors only from pages on those origins, so a key copied into another site is refused. An empty list accepts any origin. To report from local development, add your dev server's origin, such as http://localhost:5173, or create a second key for it.
Use a browser key here, never the server key your backend uses. Vigilon refuses a server key for browser errors, and a server key in your JavaScript would let anyone send traces as your backend.
Start the SDK
Call init once, as early as possible in your app's entry point, so it is running before the code you want to watch:
import { init } from "@vigilon/browser";
init({
apiKey: "[YOUR_API_KEY]",
appName: "storefront",
environment: "production",
appVersion: "2026.11.05-1",
});
If your entry point imports the rest of your app, call init in a module of its own, such as instrument.ts, and import that module first. Imports run before the importing module's own code, so an init written further down would start only after every imported module had loaded, missing their errors.
appName and environment are required. Set appVersion to your release, such as a build number or commit SHA, so Vigilon can tell which release introduced an error.
init returns false and logs the reason when it cannot start. During server-side rendering there is no window, so init and every other function do nothing, and you can import the package from code that runs on both sides.
Without a bundler, load the script-tag build, which exposes window.Vigilon. Pin an exact version, so a release never changes your page without a deploy:
<script src="https://unpkg.com/@vigilon/browser@0.2.24/dist/vigilon.min.js" crossorigin="anonymous"></script>
<script>
Vigilon.init({
apiKey: "[YOUR_API_KEY]",
appName: "storefront",
environment: "production",
});
</script>
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.
If init returns false, the SDK did not start, and the console shows a [Vigilon] not started: error with the reason. One cause is an apiKey still set to a placeholder in square brackets, as in the samples above. Otherwise, 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.