SigSentry Documentation

Every component and hook in @sigsentry/react reads its client from context. Wrap your app — or the part of it that uses SigSentry — in <SigSentryProvider> once, and the rest is plumbing-free.

Minimum setup

import { SigSentryProvider, AnalysisWidget } from '@sigsentry/react';

export function App(): JSX.Element {
  return (
    <SigSentryProvider apiKey={process.env.NEXT_PUBLIC_SIGSENTRY_KEY!}>
      <AnalysisWidget />
    </SigSentryProvider>
  );
}

Provider props

Prop	Type	Required	Default	Description
`apiKey`	`string`	yes	—	A SigSentry public key (`ss_pub_`). The SDK throws at construction if you pass an `ss_secret_` or `ss_org_*` key, so misuse fails loudly.
`baseUrl`	`string`	no	`https://api.sigsentry.com`	Override the API host (self-hosted, staging, etc.).
`theme`	`'light' \| 'dark' \| 'auto'`	no	`'auto'`	Color theme. `'auto'` follows the OS `prefers-color-scheme`.
`children`	`ReactNode`	yes	—	Anything that uses SigSentry components or hooks.

Only ss_pub_* keys are safe in client bundles. The SDK refuses to construct with ss_secret_* or ss_org_* keys — failure is at construction time, not runtime, so you'll catch a misconfiguration before it ships. Permissions on ss_pub_* keys are platform-locked to analysis:create and analysis:read, so a leaked key has bounded blast radius. Rotate anyway if leaked.

Mint an SDK key in the dashboard

Open Project → API Keys, switch to the SDK keys tab, and click Create key. The form mints an ss_pub_* with permissions locked to the SDK-safe set. See API keys.

Expose it via your build environment

Use your framework's public-env convention so it ends up in the client bundle, not the server:

# Next.js
NEXT_PUBLIC_SIGSENTRY_KEY=ss_pub_...

# Vite
VITE_SIGSENTRY_KEY=ss_pub_...

Pass it to the provider at the app root

<SigSentryProvider apiKey={process.env.NEXT_PUBLIC_SIGSENTRY_KEY!}>
  {children}
</SigSentryProvider>

Provider placement

The provider must be above any component or hook that uses SigSentry. Hooks throw useSigSentryContext must be used within a <SigSentryProvider> if they can't find one in the tree.

A common pattern is to wrap only the route or section that needs diagnostics:

// app/support/layout.tsx
'use client';

import { SigSentryProvider } from '@sigsentry/react';

export default function SupportLayout({ children }: { children: React.ReactNode }): JSX.Element {
  return (
    <SigSentryProvider
      apiKey={process.env.NEXT_PUBLIC_SIGSENTRY_KEY!}
      theme="auto"
    >
      {children}
    </SigSentryProvider>
  );
}

You can also mount multiple providers with different keys (e.g. separate keys per project) — each subtree gets its own client instance.

Custom backend

If you proxy the SigSentry API through your own infrastructure, point the provider at that host:

<SigSentryProvider
  apiKey={publicKey}
  baseUrl="https://api.your-company.com/sigsentry"
>
  {children}
</SigSentryProvider>

The base URL is used as a prefix for all requests; trailing slashes are stripped automatically.

Configuration