Documentation

Configuration

Every wutbug.init() option, with its type, default value and what it does.

wutbug.init(options) takes an object. Only projectKey is required. Appearance options can also be edited in the dashboard: whatever you pass in code always wins over the dashboard (see Appearance).

TypeScript

import wutbug from '@wutbug/sdk';

wutbug.init({
  projectKey: 'pk_your_key',
  endpoint: 'https://api.wutbug.dev',
  release: '2026.11.3',
  locale: 'en',
  position: 'bottom-right',
  launcherLabel: 'Something not working?',
  theme: { accent: '#ea580c', mode: 'auto', radius: 'round' },
  privacy: { redactKeys: ['ssn', 'dni'], blockSelector: '.card-details' },
  ignoreUrls: ['https://analytics.example.com', /\/health$/],
  beforeSend: (report) => report,
});

General options

Option	Type	Default	Description
`projectKey`	`string`	—	Required. The project's public key (`pk_…`).
`endpoint`	`string`	—	Wutbug API URL. Without it, the SDK works in local mode: it downloads the report as JSON instead of sending it.
`release`	`string`	—	Your app's version (commit SHA or `2026.11.3`). Must match the one you use when uploading source maps. Maximum 100 characters.
`locale`	`'en' \| 'es' \| 'auto'`	`'auto'`	Widget language. `auto` uses `navigator.language` (Spanish if it starts with `es`, otherwise English).
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	`'bottom-right'`	Corner of the floating button. The form opens from the same corner.
`launcher`	`boolean`	`true`	`false` hides the floating button. Open the form with `wutbug.open()` or an element with `data-wutbug-open`.
`launcherLabel`	`string`	—	Button text. Empty: icon only, and the text appears on hover.
`theme`	`object`	see below	Colors, light/dark mode, corners and font.
`remoteConfig`	`boolean`	`true`	Downloads the appearance configured in the dashboard. `false` uses only what you set in code.
`bufferMs`	`number`	`120000`	How much history (in ms) is kept in memory for replay, console and network.
`capture`	`object`	all `true`	What gets captured: `{ replay, console, network }`.
`privacy`	`object`	see below	Masking and redaction. See Privacy.
`ignoreUrls`	`(string \| RegExp)[]`	`[]`	Requests that are never recorded. A string is matched as a URL prefix.
`beforeSend`	`(report) => report \| null`	—	Last chance to edit the report or discard it (return `null`). Can be `async`.
`autoCapture`	`object`	`{ mode: 'off' }`	Automatic or suggested reports when an error occurs. Wins over the dashboard configuration, field by field. See Auto-capture.
`debug`	`boolean`	`false`	Logs the SDK's internal activity to the console.

`theme`

Option	Type	Default	Description
`accent`	`string` (hex)	`#6d5dfc`	Main color: floating button, buttons and focus.
`accentDark`	`string` (hex)	`#8b7dff`	Main color in dark mode. If you set `accent` in code and not `accentDark`, `accent` is used in both modes.
`mode`	`'auto' \| 'light' \| 'dark'`	`'auto'`	`auto` follows the user's system preference.
`radius`	`'sharp' \| 'default' \| 'round'`	`'default'`	Corner rounding.
`font`	`'system' \| 'inherit'`	`'system'`	`inherit` uses your page's font instead of the system font.

The text color on the button (white or black) is chosen automatically, based on contrast with accent.

`capture`

Option	Type	Default	Description
`replay`	`boolean`	`true`	Records the DOM with rrweb (loaded when the browser is idle).
`console`	`boolean`	`true`	Records `console.*`, uncaught errors, rejected promises and resources that failed to load.
`network`	`boolean`	`true`	Records `fetch` and `XMLHttpRequest`.
`behavior`	`boolean`	`true`	Behavior signals: rage clicks, dead clicks, long tasks and Web Vitals. See Auto-capture.

`privacy`

Option	Type	Default	Description
`maskAllInputs`	`boolean`	`true`	Masks the value of all inputs, textareas and selects in the replay and screenshot. Passwords are always masked.
`maskTextSelector`	`string`	—	Additional CSS selector whose text is masked (besides `.wutbug-mask`).
`blockSelector`	`string`	—	Additional CSS selector for elements that are hidden completely (besides `.wutbug-block`).
`redactHeaders`	`string[]`	see Privacy	Headers whose value is replaced with `[REDACTED]`. They are added to the defaults.
`redactKeys`	`string[]`	see Privacy	Regex sources (case-insensitive) for JSON key names, form fields and URL parameters. They are added to the defaults.
`redactPatterns`	`RegExp[]`	`[]`	Extra expressions that are replaced in all captured text (console, URLs, bodies).
`captureBodies`	`boolean`	`true`	Captures request and response bodies. `false` stores only method, URL, status, timings and headers.
`maxBodyLength`	`number`	`10000`	Maximum characters per body. Anything beyond that is truncated.

`beforeSend`

Receives the complete report right before it is sent. Return the report (modified or not) to send it, or null to discard it. If the function throws, the report is not sent.

TypeScript

wutbug.init({
  projectKey: 'pk_your_key',
  endpoint: 'https://api.wutbug.dev',
  beforeSend(report) {
    // Don't send reports from test environments
    if (location.hostname.endsWith('.local')) return null;
    // Remove a field from the metadata
    delete report.metadata.internalId;
    return report;
  },
});

The report includes description, reporterEmail, environment, user, metadata, console, network, replay, screenshot and video. See Captured data.

Precedence

Options passed to init() in code.
Appearance saved in the dashboard (if remoteConfig is true).
Default values.

The dashboard appearance is downloaded from GET /v1/widget-config and cached for 5 minutes per tab, so changes reach your users without redeploying.

← PreviousFramework guides Next →JavaScript API

Configuration

#General options

#theme

#capture

#privacy