Skip to content

Documentation

JavaScript API

The functions the SDK exports, how to open the form from your own UI and the available HTML attributes.

The package exports the individual functions and a default object with the same functions. With the script tag, all of them are available on window.wutbug.

TypeScript
import wutbug from '@wutbug/sdk';
// or: import { init, setUser, setMetadata, open, close, destroy, getClient } from '@wutbug/sdk';
FunctionDescription
init(options)Starts capturing and shows the widget. Calling it again replaces the previous instance. Returns the client.
setUser(user | null)Associates the person using the app with upcoming reports. null on sign-out.
setMetadata(obj)Adds key/value pairs (plan, tenant, feature flags…) to upcoming reports. Merged with previous values.
open(options?)Opens the form. { description } pre-fills it.
close()Closes the form.
destroy()Removes the widget, stops capturing and restores console, fetch and XMLHttpRequest.
getClient()Returns the active instance (or null). Advanced use.

All of them except init are safe to call before initialization: they simply do nothing.

init(options)

TypeScript
wutbug.init({ projectKey: 'pk_your_key', endpoint: 'https://api.wutbug.dev' });

Throws an error if called outside the browser or without projectKey. All options are in Configuration.

setUser(user)

TypeScript
wutbug.setUser({ id: 'u_42', email: 'ana@acme.com', name: 'Ana', plan: 'pro' });

id, email and name are optional, and you can add other fields with JSON values. If the user doesn't type an email in the form, user.email is used as the report's contact email (to notify them when it's resolved and for the conversation with the team).

setMetadata(metadata)

TypeScript
wutbug.setMetadata({ tenant: 'acme', flags: { newCheckout: true } });
wutbug.setMetadata({ cart: 3 }); // added to the previous values

Values must be JSON-serializable. Don't put secrets here: metadata is stored as-is.

open(options) and close()

TypeScript
// From a "Help → Report a bug" menu
wutbug.open();

// From an error boundary, with the description pre-filled
wutbug.open({ description: 'Error loading the cart' });

If the widget UI hasn't finished loading yet, open() stays pending and the form opens as soon as it's ready.

HTML attributes

Without writing any JavaScript, any element with data-wutbug-open opens the form on click. data-wutbug-description pre-fills it.

HTML
<button data-wutbug-open>Report a bug</button>

<a href="#" data-wutbug-open data-wutbug-description="The invoice PDF won't download">
  Trouble with your invoice?
</a>

Combine it with launcher: false (or data-launcher="false") to use only your own button.

AttributeWhereEffect
data-wutbug-openAny elementOpens the form on click.
data-wutbug-descriptionAlongside data-wutbug-openPre-fills the description.
class="wutbug-mask" or data-wutbug-maskAny elementMasks its text in the replay and screenshot.
class="wutbug-block" or data-wutbug-blockAny elementHides it completely (it appears as a gray block).

destroy()

TypeScript
wutbug.destroy();

Use it if the person withdraws consent, when unmounting in development or in tests. It restores the original console, fetch and XMLHttpRequest methods, stops the replay and clears the in-memory buffers.

TypeScript types

The package includes types. The most useful ones:

TypeScript
import type { WutbugOptions, ReportPayload, ReportUser, PrivacyConfig, OpenOptions } from '@wutbug/sdk';
import { MASK_CLASS, BLOCK_CLASS, SDK_VERSION } from '@wutbug/sdk'; // 'wutbug-mask', 'wutbug-block'
← PreviousConfigurationNext →Appearance