npm package: @proliferate_ai/browser
Description: Proliferate browser SDK for exception monitoring
Author: Proliferate
Latest version: 1.4.1

# @proliferate_ai/browser

Minimal, production-grade browser SDK for exception monitoring. Zero dependencies, TypeScript-first, crash-proof.

## Installation

```bash
npm install @proliferate_ai/browser
# or
yarn add @proliferate_ai/browser
# or
pnpm add @proliferate_ai/browser
```

## Quick Start

### 1. Install the build plugin (recommended)

The build plugin automatically injects the release ID from your git SHA:

```bash
npm install @proliferate_ai/build-plugins --save-dev
```

See [@proliferate_ai/build-plugins](../build-plugins/README.md) for setup instructions.

### 2. Initialize the SDK

```typescript
import { init } from '@proliferate_ai/browser';

init({
  dsn: 'https://api.proliferate.dev/v1/errors',
  apiKey: 'pk_live_your_api_key_here',
  // release is auto-detected if using @proliferate_ai/build-plugins
});
```

Or with manual release ID:

```typescript
init({
  dsn: 'https://api.proliferate.dev/v1/errors',
  apiKey: 'pk_live_your_api_key_here',
  release: 'v1.2.3', // or git SHA
});
```

## Features

- **Automatic error capture**: Catches uncaught exceptions and unhandled promise rejections
- **Manual capture**: Report caught errors from try/catch blocks
- **User context**: Associate errors with users
- **Tags**: Categorize errors with custom tags
- **Crash-proof**: SDK errors never crash your application
- **SSR-safe**: Works with Next.js, Remix, and other SSR frameworks
- **Tiny bundle**: < 5KB gzipped, zero dependencies

## API Reference

### `init(options)`

Initialize the SDK. Call this once at application startup.

```typescript
interface InitOptions {
  /** API endpoint for sending error events. */
  dsn: string;
  /** API key for authentication (starts with pk_live_ or pk_test_). */
  apiKey: string;
  /** Release ID for source map resolution. Auto-detected if using build plugins. */
  release?: string;
  /** Environment name (e.g., 'production', 'staging'). Defaults to 'production'. */
  environment?: string;
}
```

### `captureException(error, context?)`

Manually capture an exception.

```typescript
import { captureException } from '@proliferate_ai/browser';

try {
  await riskyOperation();
} catch (error) {
  captureException(error, {
    tags: { feature: 'checkout' },
  });
}
```

### `setUser(user)`

Set user context for all future error reports.

```typescript
import { setUser } from '@proliferate_ai/browser';

// After login
setUser({
  id: 'user_123',
  email: 'user@example.com',
});

// After logout
setUser(null);
```

### `setTag(key, value)`

Set a tag for all future error reports.

```typescript
import { setTag } from '@proliferate_ai/browser';

setTag('feature', 'checkout');
setTag('env', 'production');
```

### `removeTag(key)`

Remove a previously set tag.

```typescript
import { removeTag } from '@proliferate_ai/browser';

removeTag('feature');
```

## React / Next.js Integration

The SDK provides React components for easy integration with React and Next.js apps.

### Setup (Next.js App Router)

```tsx
// app/layout.tsx
import { Proliferate, ErrorBoundary } from '@proliferate_ai/browser/react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <Proliferate
          dsn="https://api.proliferate.dev/v1/errors"
          apiKey="pk_live_your_api_key_here"
        />
        <ErrorBoundary fallback={<div>Something went wrong</div>}>
          {children}
        </ErrorBoundary>
      </body>
    </html>
  );
}
```

### `Proliferate` Component

Initializes the SDK. Handles client-side initialization automatically (includes `"use client"` directive).

```tsx
import { Proliferate } from '@proliferate_ai/browser/react';

<Proliferate
  dsn="https://api.proliferate.dev/v1/errors"
  apiKey="pk_live_..."
  environment="production"  // optional
  release="v1.2.3"          // optional, auto-detected with build plugins
/>
```

### `ErrorBoundary` Component

Catches React render errors and reports them to Proliferate.

```tsx
import { ErrorBoundary } from '@proliferate_ai/browser/react';

<ErrorBoundary
  fallback={<ErrorPage />}
  onError={(error, info) => console.error('Caught:', error)}  // optional
  captureContext={{ tags: { component: 'checkout' } }}        // optional
>
  <MyApp />
</ErrorBoundary>
```

### Non-React or Manual Setup

If you're not using React, or need manual control:

```typescript
import { init } from '@proliferate_ai/browser';

init({
  dsn: 'https://api.proliferate.dev/v1/errors',
  apiKey: 'pk_live_your_api_key_here',
});
```

## Source Maps

For stack traces to be readable, you need to:

1. Use a build plugin to inject the release ID
2. Upload source maps with the same release ID

### Using Build Plugins

Install the build plugin package:

```bash
npm install @proliferate_ai/build-plugins --save-dev
```

Configure your bundler (see [@proliferate_ai/build-plugins](../build-plugins/README.md)):

```javascript
// vite.config.js
import { proliferateVite } from '@proliferate_ai/build-plugins/vite';

export default {
  plugins: [proliferateVite()],
};
```

The plugin automatically:
- Extracts the git SHA
- Injects `__PROLIFERATE_RELEASE__` global
- Logs the release ID during build

### Uploading Source Maps

After building, upload your source maps:

```bash
proliferate sourcemaps upload \
  --release $(git rev-parse --short HEAD) \
  --path ./dist
```

## License

MIT