Integrate an SDK · Web

Web & React SDK

A framework-independent browser SDK, thin React helpers, and a Playwright runner the CLI launches per replay attempt. Capsules carry sdk.name: @bugcapsule/web and runtime.name: web.

1. Install

cd bug_capsule_web_sdk
npm install && npm run build && npm run pack:all     # dist-packages/*.tgz

cd ../your-app
npm install ../bug_capsule_web_sdk/dist-packages/bugcapsule-web-0.3.0.tgz \
            ../bug_capsule_web_sdk/dist-packages/bugcapsule-react-0.3.0.tgz
npm install -D ../bug_capsule_web_sdk/dist-packages/bugcapsule-web-replay-0.3.0.tgz
# Once published: npm install @bugcapsule/web @bugcapsule/react; npm install -D @bugcapsule/web-replay

2. Initialize before rendering

import { BugCapsule, networkIntegration, historyIntegration, localStorageIntegration } from '@bugcapsule/web';

await BugCapsule.init({
  appVersion: '1.4.0',
  appBuild: '52',
  mode: 'qa',                                   // DEFAULT IS 'production' (10% sampled) — set it
  gitSha: import.meta.env.VITE_BUGCAPSULE_GIT_SHA,
  backend: { url: 'https://api.bugcapsule.com', ingestKey: 'bci_…' }, // never a bcs_ secret key
  integrations: [
    networkIntegration({ rules: [{ method: 'POST', path: '/api/checkout', ignoreBodyFields: ['timestamp', 'nonce'] }] }),
    historyIntegration(),
    localStorageIntegration({ allowPrefixes: ['shop.'] }),
  ],
  allowReplay: import.meta.env.DEV || import.meta.env.VITE_BUGCAPSULE_ALLOW_REPLAY === 'true',
});

renderApp();

• Await init before rendering. In replay it restores storage and state there.
• Call it before any code keeps its own reference to fetch, or that code bypasses capture (and replay's network serving).
• A second call throws. Setup has a 5 s budget (setupTimeoutMs); if it or an integration fails, the app runs without capture.
• Leaving out mode means 'production', which records only productionSampleRate (10%) of sessions. Set 'qa' for QA builds.

3. Get your origin allowed

Browsers only let the SDK reach BugCapsule from origins your project allows. Send your BugCapsule team the exact origins (scheme, host and port) your app runs on, for example:

https://app.example.com
https://staging.app.example.com
http://127.0.0.1:4317        # local QA builds

Until an origin is allowed, the browser console shows CORS errors and nothing is uploaded. The SDK never sends cookies to BugCapsule.

4. Make more bugs replayable

React

import { useBugCapsuleAction, useTrackedState, useBugCapsuleState,
         BugCapsuleErrorBoundary, BugCapsuleCaptureButton } from '@bugcapsule/react';
import { BugCapsuleRouteListener } from '@bugcapsule/react/react-router';

function Cart() {
  const [coupon, setCoupon] = useTrackedState('cart.coupon', '');
  const [cart, setCart] = useState(emptyCart);
  useBugCapsuleState('cart', cart, setCart);                  // checkpoint + restore
  const placeOrder = useBugCapsuleAction('cart.checkout', async () => { … });
  return <>
    <input value={coupon} onChange={(e) => setCoupon(e.target.value)} />
    <button data-bugcapsule-action="cart.checkout" onClick={() => void placeOrder()}>Checkout</button>
  </>;
}

<BrowserRouter>
  <BugCapsuleRouteListener />                         {/* route events with push/pop/replace */}
  <BugCapsuleErrorBoundary fallback={<Oops />}><Routes>…</Routes></BugCapsuleErrorBoundary>
  <BugCapsuleCaptureButton />                         {/* renders nothing in production or replay */}
</BrowserRouter>

Integrations

Network: fetch and XMLHttpRequest

networkIntegration({
  fetch: true, xhr: true,                       // or fetchIntegration() / xhrIntegration()
  rules: [{ method: 'POST', path: '/api/orders/:id', ignoreBodyFields: ['nonce'] }],
  ignoreQuery: ['_', 'ts', 'timestamp', 'nonce', 'cachebust'],   // default
  maxBinaryBytes: 64 * 1024, maxKeyBodyBytes: 64 * 1024, maxBodyWaitMs: 30_000,
  exclude: ({ method, url }) => url.includes('/api/payments'),   // keeps method, URL, status, timing only
});

• The SDK reads a clone() of each response up to maxBodyBytes (256 KiB text, 64 KiB binary) and cancels the clone; the app consumes the original stream unchanged. text/event-stream is omitted.
• ReadableStream request bodies, FormData and XHR Blob bodies are never read: keyed without a body hash.
• App wrappers installed after init sit above the SDK's, so app interceptors still run in replay; only the bytes on the wire come from the capsule.

Storage, history, IndexedDB

localStorageIntegration({ allowPrefixes: ['shop.'], denyPrefixes: ['shop.token'] })   // allowPrefixes is required
sessionStorageIntegration({ allowPrefixes: ['checkout.'] })
historyIntegration({ sanitizeLocation: (l) => l.replace(/\/reset\/[^/]+/, '/reset/:token') })
indexedDbIntegration([{ name: 'offline-cart', snapshot: async () => readCart(), restore: async (d) => writeCart(d) }])

historyIntegration wraps pushState/replaceState and listens to popstate/hashchange. Cookies, DOM content, input values (except tracked inputs) and storage outside the allowlist are never captured.

Configuration reference

Methods

BugCapsule.action(id, handler)                    // wraps handler
BugCapsule.actionWithPayload(id, (payload) => …)
BugCapsule.trackInput(id, el, { sensitive })      // returns dispose()
BugCapsule.trackValue(id, set, { sensitive })     // { changed(value), dispose() } for custom widgets
BugCapsule.fail(id, message?); BugCapsule.check(id, condition, message?); BugCapsule.reportError(e)
BugCapsule.log(message, 'debug' | 'info' | 'warn' | 'error')
BugCapsule.route(location, source?, action?)      // explicit route events
BugCapsule.registerState(key, { serialize, restore }) // returns unregister; stateChanged(key)
await BugCapsule.capture({ note })                // CaptureResult | null
BugCapsule.now(); BugCapsule.date(); BugCapsule.random()
await BugCapsule.refreshRemoteConfig(); await BugCapsule.flushUploads()
await BugCapsule.pendingUploads(); await BugCapsule.savedCaptures()
BugCapsule.isInitialized; BugCapsule.isRecording; BugCapsule.isReplaying; BugCapsule.mode; BugCapsule.session

Replay with the CLI

{
  "runtime": "web",
  "web": {
    "url": "http://127.0.0.1:4317/",
    "installCommand": "npm ci",
    "buildCommand": "npm run build",
    "serveCommand": "npm run preview -- --port 4317 --strictPort",
    "env": { "VITE_BUGCAPSULE_ALLOW_REPLAY": "true" }
  }
}

bugcapsule run <id> -n 3                                  # builds (on the capsule's commit when pinned), serves, replays
bugcapsule verify <id> -n 3                               # builds the working tree
bugcapsule run <id> --app-url http://127.0.0.1:4317/      # against an already running build

The CLI passes BUGCAPSULE_GIT_SHA/BUGCAPSULE_GIT_DIRTY in the build environment; map them to your bundler's env (the shop demo's vite.config.ts maps them to VITE_BUGCAPSULE_GIT_SHA with define). The CLI refuses to start when something already serves web.url (it might be an old build).

Per attempt, bugcapsule-web-runner:

1. Fetches /settings and /capsule from the CLI's loopback server.
2. Launches Chromium with the recorded viewport, scale factor and locale, service workers blocked, a fresh browser context.
3. Blocks every request to an origin other than the app's (and web.allowOrigins) and reports network.escaped.
4. Restores localStorage/sessionStorage in an init script before any page script, exposes the Playwright bindings, and opens the checkpoint's location.
5. The app's own SDK (with allowReplay: true) runs the engine: real pointer input through Playwright at recorded coordinates (hit-tested against the recorded target), semantic actions, tracked inputs, synthetic lifecycle; fetch/XHR served from the capsule.
6. Posts the report to /result and prints a BUGCAPSULE_RESULT:: line. Default timeout 120 s.

Uploads and storage

• IndexedDB database bugcapsule: outbox (10 / 10 MiB / 7 days), newest 20 saved captures, cached remote config. Without IndexedDB the SDK keeps them in memory.
• Several tabs share one queue; only one uploads at a time (Web Locks, or a lease record on insecure origins). Queues survive reloads; nothing relies on an upload finishing during unload.
• Failed uploads retry with backoff from 30 s up to 1 h; a capsule BugCapsule rejects is dropped.
• Kill switch: purges queue and saved captures, persists. A rejected ingest key also deletes the queue and saved captures and stops capture for the page session.

Shop demo

examples/shop: React app with four planted bugs (race, legacy cart, discontinued item, coupon) and a local API (api-server.mjs, port 4318). Environment: VITE_BUGCAPSULE_BACKEND_URL, VITE_BUGCAPSULE_INGEST_KEY, VITE_BUGCAPSULE_ALLOW_REPLAY, VITE_BUGCAPSULE_DEMO_FIX (race|legacy|discontinued|coupon), VITE_SHOP_API_URL.

node examples/shop/api-server.mjs                       # shop API on 127.0.0.1:4318
cd examples/shop
VITE_BUGCAPSULE_BACKEND_URL=https://api.bugcapsule.com VITE_BUGCAPSULE_INGEST_KEY=bci_… \
VITE_BUGCAPSULE_ALLOW_REPLAY=true npx vite build && npx vite preview --port 4317 --strictPort

Browsers and limitations

• Hover-only interactions aren't recorded (moves only while pressed); keyboard input only through tracked inputs.
• WebSockets, EventSource payloads, service workers, sendBeacon and third-party iframes are not captured.
• Synchronous XHR replays without its recorded latency. Cross-origin script errors without CORS headers arrive as Script error..
• A fix that makes the app send requests the recording never saw verifies as INCONCLUSIVE, never FIXED (network.unrecorded).
• BugCapsuleCaptureButton clicks are still recorded as pointer events.
• No consent, user-identify or breadcrumb API: use enabled, labels, log(), route().