Configuration

Configure Cluebase options in `CluebaseProvider` for this project:
1. Locate the `CluebaseProvider` component at your application root (`app/layout.tsx`, `pages/_app.tsx`, or `src/main.tsx`).
2. Pass configuration props as needed:
   - `apiKey`: string (required, e.g., `process.env.NEXT_PUBLIC_CLUEBASE_API_KEY` or `import.meta.env.VITE_CLUEBASE_API_KEY`)
   - `user`: { id, email?, name?, metadata? } (optional, the signed-in end user; the agent then greets them by name and never asks for contact details)
   - `identity`: boolean (optional, defaults true; set false to disable end-user identity entirely, dropped in the browser before anything is sent)
   - `captureFetch`: boolean (optional, defaults true; watches `fetch` so a request that returns 500 or fails outright is reported without wrapping call sites. Set false to switch that off)
   - `environment`: 'development' | 'production' (optional, defaults to 'production')
   - `sessionId`: string (optional, for grouping errors by session)
   - `sanitize`: (text: string) => string (optional, adds custom PII redaction rules on top of the built-in ones)
   - `onError`: (report) => void (optional, a callback fired for every reported error)
3. Store the publishable key in environment variables (`.env.local` / `.env`). It starts with `cb_pk_` and is safe to expose in the browser bundle: it can only report errors, and only from the domains listed in the project's settings.
   If reports are not arriving, check the project's Allowed origins first: Cluebase rejects reports from any domain not on that list, and an empty list rejects everything. Scheme and port are ignored, so `localhost` covers any dev port, but matching is otherwise exact and there are no wildcards.
4. If you wire up `user`, pass only values the app already has. Never read them from localStorage, cookies, tokens, the DOM, or form fields, and never derive a name from an email address.

The CluebaseProvider accepts several optional props to customise its behaviour.

Props reference

apiKey required

Your project's publishable key, starting with cb_pk_. It ships in your browser bundle, which is expected: it can only report errors, and only from the domains listed in your project settings.

apiKey: string

environment

Tags reported errors with the environment they occurred in.

environment?: 'development' | 'production' // default: 'production'

sessionId

An optional identifier attached to every report, useful for grouping errors by session.

sessionId?: string

userId deprecated

Superseded by user. It only ever tagged the report client-side and was never recorded against the incident, so it could not be searched, displayed, or used to delete a person's data on request. Pass a user object instead.

user

The signed-in end user, if your app knows who they are. Pass it and the agent greets them by name, never asks for an email, and the incident reaches your team with a real person attached instead of an anonymous visitor.

user?: {
  id: string        // required if user is supplied at all
  email?: string
  name?: string
  metadata?: Record<string, string | number | boolean>
}

Only id is required. An app that knows who someone is but would rather not share their email still gets the identified experience. See Identifying users for Clerk and NextAuth examples.

identity

Set false to switch off end-user identity completely. The user prop is ignored, identify()becomes a no-op, and nothing about your end users is transmitted. Errors are still captured and your team is still alerted; only the "who" is withheld, and the agent falls back to asking for contact details in conversation.

identity?: boolean // default: true

The drop happens in the browser, before anything reaches the network, so this is verifiable rather than a promise about what our servers do with the data.

sanitize

Runs on top of the SDK's built-in PII redaction (emails, SSNs, phone numbers, and credit-card-shaped digit runs, applied automatically). Use this to add your own rules (see Custom Errors for an example).

sanitize?: (text: string) => string

onError

A callback fired with the full error report every time one is sent, regardless of source.

onError?: (report: CluebaseErrorReport) => void

Allowed origins

Your publishable key ships in your browser bundle, so anyone who views source on your site can read it. What stops them using it is this: Cluebase only accepts error reports from the domains you list, and the browser attaches the sending origin to every request in a way the page cannot forge.

You set the first one when you create the project. To add more, go to your project settings and edit Allowed origins:

app.example.com, www.example.com, localhost

Scheme and port are ignored, so app.example.com covers both http and https, and localhost covers localhost:3000, localhost:5173 and any other port you develop on. You do not need to list them separately.

Matching is exact, and there are no wildcards

example.com does not cover app.example.com. Each host you send from needs its own entry. Wildcards are not supported on purpose: matching by suffix is how a domain like app.example.com.attacker.io gets treated as a match for example.com, and that would defeat the point of the list.

Preview deployments

Preview builds on Vercel, Netlify and similar hosts get a fresh hostname per deployment, so they will not match your allowlist and their errors will be rejected. If you want reports from a specific preview, add that exact hostname while you need it. Production and staging domains are stable and only need adding once.

Error classification

Crashes caught automatically (by the root boundary or the global error/rejection listeners) are classified with no configuration needed. useCluebaseFetch and manually tagging reportError() with an errorType are both opt-in (see Manual Reporting for details).