# Browser & React SDK

Capture browser errors, page loads, and network traces with @prilog/monitoring-browser and connect frontend activity to backend spans.

## Install

```bash
npm install @prilog/monitoring-browser
```

Create a monitoring connection in Prilog and copy its publishable ingest DSN. See [monitoring setup](/docs/monitoring/#provision-a-connection).

## Initialize in your entry point

Initialize once, before rendering your application, in your TypeScript entry point, such as `src/main.ts` or React's `src/main.tsx`:

```typescript
import { init } from '@prilog/monitoring-browser';

const monitoring = init({
  dsn: 'YOUR_PRILOG_DSN',
  serviceName: 'checkout-web',
  environment: 'production',
});

// Render React or start your existing browser application here.
```

Replace `YOUR_PRILOG_DSN` with the DSN from Prilog. The SDK instruments document loading, fetch, and XMLHttpRequest and captures global errors and unhandled promise rejections. It sends a startup log and span to verify the connection.

The SDK currently needs a local module declaration for strict TypeScript compilation; see [TypeScript setup](/docs/monitoring/#typescript-setup).

Without a DSN, or outside a browser, `init` returns a disabled monitor. In an SSR application, initialize in the browser entry point; use the [Node SDK](/docs/nodejs/) for server instrumentation.

## Spans and exceptions

```typescript
import { withSpan, log, captureException } from '@prilog/monitoring-browser';

withSpan('checkout.validate', () => {
  log('info', 'Order validated', { 'order.id': 'example-order' });
});

// In your existing error boundary or handled-error path:
captureException(new Error('Checkout failed'));
```

`withSpan(name, callback, attributes?)` returns the callback result and records and rethrows errors. `log(level, message, attributes?)` supports `debug`, `info`, `warn`, and `error`. `captureException(error)` records the exception and stack trace.

## Configuration reference

- `dsn` — publishable ingest DSN; required to enable monitoring.
- `serviceName` — defaults to `frontend`.
- `environment` — defaults to `production`.
- `release` — defaults to `unknown`.
- `tracePropagationTargets` — URL strings or regular expressions for requests that receive trace headers; defaults to the current origin.

## Distributed tracing and CORS

For a frontend calling a separate API origin, configure the target explicitly:

```typescript
import { init } from '@prilog/monitoring-browser';

const monitoring = init({
  dsn: 'YOUR_PRILOG_DSN',
  serviceName: 'checkout-web',
  tracePropagationTargets: ['https://api.example.com'],
});
```

Allow `traceparent`, `tracestate`, and `baggage` request headers in the API's CORS policy. The backend must preserve the incoming trace context and export its spans. Give frontend and backend different service names.

If your application uses Content Security Policy, add your Prilog ingest origin to `connect-src`. Use the origin from the DSN shown in your monitoring setup.

## Lifecycle

The SDK attempts to flush telemetry on `pagehide`. Await `monitoring.shutdown()` when explicitly tearing down a monitored application. A page closing abruptly can prevent pending network exports from finishing.

The browser DSN grants ingestion only. Do not put CLI access tokens or OAuth credentials in browser code. See the [OTLP contract](/docs/otlp/) for the underlying transport.