@proliferate_ai/browser
v1.4.1
Published
Proliferate browser SDK for exception monitoring
Maintainers
pabliferateReadme
@proliferate_ai/browser
Minimal, production-grade browser SDK for exception monitoring. Zero dependencies, TypeScript-first, crash-proof.
Installation
npm install @proliferate_ai/browser
# or
yarn add @proliferate_ai/browser
# or
pnpm add @proliferate_ai/browserQuick Start
1. Install the build plugin (recommended)
The build plugin automatically injects the release ID from your git SHA:
npm install @proliferate_ai/build-plugins --save-devSee @proliferate_ai/build-plugins for setup instructions.
2. Initialize the SDK
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:
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.
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.
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.
import { setUser } from '@proliferate_ai/browser';
// After login
setUser({
id: 'user_123',
email: '[email protected]',
});
// After logout
setUser(null);setTag(key, value)
Set a tag for all future error reports.
import { setTag } from '@proliferate_ai/browser';
setTag('feature', 'checkout');
setTag('env', 'production');removeTag(key)
Remove a previously set tag.
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)
// 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).
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.
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:
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:
- Use a build plugin to inject the release ID
- Upload source maps with the same release ID
Using Build Plugins
Install the build plugin package:
npm install @proliferate_ai/build-plugins --save-devConfigure your bundler (see @proliferate_ai/build-plugins):
// 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:
proliferate sourcemaps upload \
--release $(git rev-parse --short HEAD) \
--path ./distLicense
MIT