@heizen-labs/bugs-sdk

v1.2.1

Published

3 days ago

Floating bug report widget for React sites.

0High
0Medium
0Low

bugs-sdk

A floating bug report widget for React applications. Drop it in, give it an API key, and let users report bugs with descriptions, screenshots, screen recordings, and metadata — all submitted to your bug tracking backend.

Install

npm install @heizen-labs/bugs-sdk

Peer dependencies: react ^19.0.0, react-dom ^19.0.0

Quick Start

import { BugsSdk } from "@heizen-labs/bugs-sdk";

export function App() {
  return (
    <BugsSdk apiKey="hzs_your_api_key" />
  );
}

That's it. The widget renders a floating "Report bug" button in the bottom-right corner. No CSS import needed — styles are bundled in.

Props

| Prop | Type | Default | Description | |---|---|---|---| | apiKey | string | required | Your Heizen API key for submitting bug reports | | defaultPosition | "top-left" \| "top-right" \| "bottom-left" \| "bottom-right" \| "left" \| "right" | "bottom-right" | Which corner the widget sits in. "left" and "right" are legacy aliases for bottom corners | | endpoint | string | Heizen bug report endpoint | Override the bug report submission endpoint | | metadata | Record<string, unknown> | undefined | Custom key-value pairs attached to every report (user info, environment, feature flags, etc.) | | source | string | "feedback-widget" | Identifies where the report came from. Useful when the same API key serves multiple apps |

Example

import { BugsSdk } from "@heizen-labs/bugs-sdk";

export function App() {
  return (
    <BugsSdk
      apiKey="hzs_xxx"
      defaultPosition="bottom-left"
      metadata={{
        userId: "usr_123",
        plan: "pro",
        environment: "staging",
      }}
      source="my-app-dashboard"
    />
  );
}

What the Widget Captures

Each submitted report includes:

Description — user-written bug report
Files — screenshots (full-page or selected area), screen recordings, or uploaded media (images, audio, video)
Page context — URL, page title, viewport dimensions, browser info
Metadata — any custom context passed via the metadata prop
Source — the source prop value

Limits

Up to 5 files per report
25MB max per file
1 video max (screen recording or uploaded)
Screen recordings capped at 60 seconds

Framework Compatibility

Works with any React 19+ setup:

Vite — just import and render
Next.js (App Router) — render in a "use client" component, typically in your root layout
Remix, CRA, etc. — same pattern, import and place once

Next.js Example

// app/layout.tsx
import { BugsSdkClient } from "./bugs-sdk-client";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <BugsSdkClient />
      </body>
    </html>
  );
}

// app/bugs-sdk-client.tsx
"use client";

import { BugsSdk } from "@heizen-labs/bugs-sdk";

export function BugsSdkClient() {
  return <BugsSdk apiKey="hzs_xxx" />;
}

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme