JavaScript / TypeScript SDK

Report errors to BugBoard in three steps: install, copy one setup file, then call it.

Source on GitHub: github.com/bug-board/bugboard-js Runs on Node 20+, browsers, and edge runtimes with nothing to install or wire up (it uses the platform fetch). The default path loads no dependencies; opt-in payload encryption lazy-loads a tiny tweetnacl sealed-box binding (tweetnacl-sealedbox-js) that ships bundled with the SDK — it loads automatically when you set an encryption key, with nothing extra to install. See Encrypting sensitive reports.

1. Install

npm i bugboard

2. Add the setup file

Create one file that configures a shared client, then import it anywhere. This keeps your keys in a single place. Pick the tab for where the client runs:

// utils/bugboard.ts
import { createClient } from 'bugboard';

// In the browser or a mobile app, use a publishable key, sent as a bearer token.
export default createClient({
    apiKey: import.meta.env.VITE_BUGBOARD_API_KEY, // bb_pub_…

    // OPTIONAL — if provided, every payload is encrypted before it leaves the client.
    // encryptionKeyId: import.meta.env.VITE_BUGBOARD_ENCRYPTION_KEY_ID,         // bbek_…
    // encryptionPublicKey: import.meta.env.VITE_BUGBOARD_ENCRYPTION_PUBLIC_KEY, // base64 X25519
});

// utils/bugboard.ts
import { createClient } from 'bugboard';

// On a server, use a secret key; requests are HMAC-signed and the secret never leaves the server.
export default createClient({
    keyId: process.env.BUGBOARD_KEY_ID, // bbk_…
    signingSecret: process.env.BUGBOARD_SIGNING_SECRET, // bb_sec_…

    // OPTIONAL — if provided, every payload is encrypted before it leaves the server.
    // encryptionKeyId: process.env.BUGBOARD_ENCRYPTION_KEY_ID,         // bbek_…
    // encryptionPublicKey: process.env.BUGBOARD_ENCRYPTION_PUBLIC_KEY, // base64 X25519

    // OPTIONAL — log reports locally instead of sending them (local debugging / dry run).
    // logLocally: true,
});

Set the matching values in your .env:

VITE_BUGBOARD_API_KEY=bb_pub_xxxxxxxx

BUGBOARD_KEY_ID=bbk_xxxxxxxx
BUGBOARD_SIGNING_SECRET=bb_sec_xxxxxxxx

3. Use it

Call a severity method with a title (required); optionally pass a description — a string or the caught error — and tags.

import bugboard from '@/utils/bugboard';

try {
    await payments.charge(order);
} catch (err) {
    bugboard.criticalHigh('Payment failed', err, ['payment', 'backend']);
}

The title is all you need:

bugboard.major('Checkout is slow');

That's it — the call returns immediately and the report is delivered in the background.

Common methods

Most apps only need these four (medium priority); each severity also has …Low and …High variants — criticalHigh, minorLow, and so on:

bugboard.critical('Payment failed', err); // highest severity
bugboard.major('Checkout is slow', err);
bugboard.moderate('Slow image upload', err);
bugboard.minor('Tooltip misaligned');

Tags are an array or a comma-separated string:

bugboard.critical('Payment failed', err, ['payments', 'checkout']);
bugboard.critical('Payment failed', err, 'payments,checkout');

Serverless / short-lived scripts

Reports deliver in the background, and the SDK flushes automatically on shutdown (Node beforeExit, browser pagehide). In environments without lifecycle hooks — lambdas, edge functions, CLI scripts — flush before returning:

await bugboard.flush();

Framework guides

The SDK is identical on every runtime — what changes is where you build the client, which key it uses, and where you flush. These guides cover each one end to end:

In an app with both a server and a client bundle, make two modules — one with the secret key that never reaches the browser, one with the publishable key that does. Adopt whatever server-only convention your framework enforces (.server.ts in SvelteKit and Remix, server-only in Next.js) so an accidental client import fails at build time rather than shipping your signing secret.

Next steps

• Framework guides — detailed integration for every major framework.
• API Reference — config options, every severity/priority variant (criticalHigh, …), and the full HTTP contract.
• Encrypting sensitive reports — keep the payload out of the browser network tab with encryptionPublicKey (the bundled tweetnacl-sealedbox-js binding auto-loads for you).
• Source on GitHub — the full SDK implementation.