Installation

You need two values from your project, which you'll find in the dashboard under Projects:

• Project key (pk_…): it is public and can go in browser code.
• Endpoint: the API URL where reports are sent.

The dashboard shows the snippet with both values already filled in. In this guide we use pk_your_key and https://api.wutbug.dev as examples.

#Option A: script tag

Paste this in the <head> of your base template. No build step or bundler needed.

<script type="module" src="https://cdn.wutbug.dev/v0/wutbug.js"
  data-project-key="pk_your_key"
  data-endpoint="https://api.wutbug.dev"></script>

With data-project-key the SDK initializes itself. You can configure the basics with attributes:

For options that have no attribute (privacy, beforeSend, ignoreUrls…), remove data-project-key and call wutbug.init({...}) yourself.

#Calls before the script loads

The script is a module and loads deferred. If you want to call wutbug.setUser() or wutbug.init() before it finishes loading, add this snippet before the script. Calls are queued and run on load:

<script>
  window.wutbug = window.wutbug || { q: [] };
  ['init', 'setUser', 'setMetadata', 'open', 'close'].forEach(function (m) {
    window.wutbug[m] = window.wutbug[m] || function () { window.wutbug.q.push([m, arguments]); };
  });
</script>
<script type="module" src="https://cdn.wutbug.dev/v0/wutbug.js"></script>
<script>
  wutbug.init({ projectKey: 'pk_your_key', endpoint: 'https://api.wutbug.dev', locale: 'en' });
</script>

If the queue contains an init, the SDK does not auto-initialize from the data-* attributes.

#Option B: npm package

npm install @wutbug/sdk
# or: pnpm add @wutbug/sdk · yarn add @wutbug/sdk · bun add @wutbug/sdk

import wutbug from '@wutbug/sdk';

wutbug.init({
  projectKey: 'pk_your_key',
  endpoint: 'https://api.wutbug.dev',
  release: '2026.11.3', // optional, required for source maps
});

init() must run only in the browser and once. If your framework renders on the server (Next.js, Nuxt, SvelteKit…), call it from code that only runs on the client. The framework guides show where.

#Identify the user

Call setUser where your app already knows the session, and pass null on sign-out. This way you know who reported and can notify them when it's resolved.

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

// on sign-out
wutbug.setUser(null);

Optionally, add context that's useful for debugging:

wutbug.setMetadata({ plan: 'pro', tenant: 'acme', featureFlags: ['new-checkout'] });

#Restrict origins

In the dashboard, in the project settings, list the domains reports are accepted from (for example https://app.acme.com). The API rejects reports from other origins. The project key is public, so this prevents someone from using it from another site.

#Verify the installation

1. Open your app: the Report a bug button should appear at the bottom right, and the console should show no [wutbug] errors.
2. Send a report that says "Installation test".
3. Open it in the dashboard. If it doesn't arrive, enable debug: true (or data-debug) and check the console.