Install the SDK

The SDK sends your app’s errors and session recordings to Opslane. Setup is one install command, one init call, and one setUser call.

Before you start, you need an ingest key for your project. The SDK accepts only keys beginning with opslane_pk_. See API keys.

The onboarding wizard puts this key directly in its setup snippet so you can send a test event immediately. The key ships in your bundle; move it to an environment variable before committing.

Privacy: session recording is on by default. Review replay privacy and masking before you deploy.

Install

npm install @opslane/sdk

React and Vue are optional peer dependencies, so you install whichever one your app already uses.

Initialize

Call init once, as early as possible in your browser entry point. Then call setUser after sign-in.

init installs handlers for uncaught errors and unhandled promise rejections, instruments console, fetch, and XMLHttpRequest, records click and submit interactions, and starts session recording. Calling it twice is a no-op, and the SDK never throws into your code.

React

import { createRoot } from 'react-dom/client';
import { init, setUser } from '@opslane/sdk';
import { OpslaneErrorBoundary } from '@opslane/sdk/react';
import App from './App';

init({
  apiKey: 'opslane_pk_...',
  environment: 'development',
  endpoint: 'https://your-opslane-instance.example.com', // https://app.opslane.com for hosted Opslane
});

// After sign-in.
setUser({ id: currentUser.id, email: currentUser.email });

createRoot(document.getElementById('root')!).render(
  <OpslaneErrorBoundary fallback={<p>Something went wrong.</p>}>
    <App />
  </OpslaneErrorBoundary>
);

The error boundary catches render errors, which React does not surface to window.onerror. Everything else, including event handlers, setTimeout, and promise rejections, goes to the global handlers init installs.

Vue 3

import { createApp } from 'vue';
import { init, setUser, opslaneVuePlugin } from '@opslane/sdk';
import App from './App.vue';

init({
  apiKey: 'opslane_pk_...',
  environment: 'development',
  endpoint: 'https://your-opslane-instance.example.com', // https://app.opslane.com for hosted Opslane
});

setUser({ id: currentUser.id, email: currentUser.email });

createApp(App).use(opslaneVuePlugin).mount('#app');

The plugin hooks app.config.errorHandler, keeping any handler you already registered, and tags each error with the failing component’s name and lifecycle hook.

Next.js

Initialize Opslane in a client component so the browser-only error handlers are installed after hydration. Create app/opslane-provider.tsx:

'use client';
import { useEffect } from 'react';
import { init } from '@opslane/sdk';

export function OpslaneProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    init({
      apiKey: 'opslane_pk_...',
      environment: 'development',
      endpoint: 'https://your-opslane-instance.example.com', // https://app.opslane.com for hosted Opslane
    });
  }, []);
  return <>{children}</>;
}

Then wrap {children} with <OpslaneProvider> in app/layout.tsx. Call setUser from a client component after sign-in, as you would in React or Vue. If your app already has a client-side authentication provider, you can initialize Opslane there instead of adding a separate provider.

Vanilla JavaScript

import { init, setUser } from '@opslane/sdk';

init({
  apiKey: 'opslane_pk_...',
  environment: 'development',
  endpoint: 'https://your-opslane-instance.example.com', // https://app.opslane.com for hosted Opslane
});

setUser({ id: 'user-123' });

Always call setUser

Every independently built bundle that calls init() must also call setUser() after authentication: the main app, embeds, iframe apps, and portal or extension panels each need their own call.

A bundle that skips setUser reports every user as anonymous. Anonymous sessions can still contribute to error impact, but Opslane cannot connect repeat activity to the same person or account, and anonymous activity cannot start a standalone session-recording issue. The dashboard flags this with No user identification. When it names one bundle or application, check its entry point.

Set the environment

environment labels where the SDK data came from. Without it, everything lands in the project’s default environment, which starts as production, so staging traffic reads as production. See environments.

Set the variables at build time. For Vite:

VITE_OPSLANE_API_KEY=opslane_pk_...
VITE_OPSLANE_ENVIRONMENT=staging

For Next.js, use NEXT_PUBLIC_OPSLANE_API_KEY and NEXT_PUBLIC_OPSLANE_ENVIRONMENT and read them from process.env.

Keep the ingest key in your deploy platform or CI secret store rather than the repository. Browsers can read the key from the built bundle, but a committed key is slow to rotate.

Capture errors yourself

import { captureException, clearUser } from '@opslane/sdk';

try {
  riskyThing();
} catch (err) {
  captureException(err instanceof Error ? err : new Error(String(err)));
  showFallbackUI();
}

clearUser(); // on logout

Throw real Error objects rather than strings. A string throw arrives with no stack frames, and Opslane classifies it as unfixable_no_app_frames (reason codes).

Upload source maps

Production stacks point at minified bundles until you upload source maps. For Vite, add the opslane() plugin and set OPSLANE_SOURCEMAP_KEY; see source maps. Only Vite has a first-party upload integration today.

Serve cross-origin scripts correctly

If your bundle is served from a different origin than your page, add crossorigin to the script tag. Without it, browsers report Script error. with no stack, and Opslane drops those events as noise.

<script type="module" crossorigin src="https://cdn.example.com/app.js"></script>

Verify

Temporarily render a button that throws new Error('opslane-test'), then click it. Use onClick={() => { throw new Error('opslane-test'); }} in React or Next.js, @click="() => { throw new Error('opslane-test') }" in Vue, or onclick="throw new Error('opslane-test')" in HTML.

The error should appear as an issue within a few seconds. Delete the test button after Opslane receives it. If nothing arrives, check the key prefix, the endpoint value on self-hosted installs, and the browser console for SDK warnings (set debug: true to see them).

Every init option, with types and defaults: SDK options.

Optional operator usage notifications

Self-hosted operators can set USAGE_EVENTS_SLACK_WEBHOOK on both server-side services to send best-effort notifications to a Slack incoming webhook. When unset, usage notifications are fully disabled.

The notifications cover user signup and login, an environment’s first SDK event, issue admission, fix PR creation, needs-human outcomes, delivered digests, and successful MCP tool calls. Delivery is fire-and-forget and is not an audit log.

Privacy: These messages can contain customer email addresses and error titles. Send them only to a private channel whose membership matches your production-data access policy, and store the webhook as a deployment secret.