@diegotsi/flint-react

Embeddable React widget that lets users report bugs directly from your app. Sends reports to a running flint-server instance.

Installation

bun add @diegotsi/flint-react
# or
npm install @diegotsi/flint-react

React 17+ is required as a peer dependency.

Usage

import { FlintWidget } from "@diegotsi/flint-react"

export default function App() {
  return (
    <>
      {/* your app */}
      <FlintWidget
        projectKey="your-project-api-key"
        serverUrl="https://your-flint-server.com"
      />
    </>
  )
}

The widget renders a floating button fixed to the bottom-right corner. Clicking it opens a modal where the user fills in a bug report.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | projectKey | string | required | API key from flint-server | | serverUrl | string | required | Base URL of your flint-server | | user | FlintUser | — | Pre-fill reporter info | | meta | Record<string, unknown> | — | Extra metadata attached to every report | | buttonLabel | string | "Reportar bug" | Label on the trigger button | | locale | "pt-BR" \| "en-US" | "pt-BR" | UI language | | theme | "light" \| "dark" \| ThemeOverride | "light" | Visual theme | | zIndex | number | 9999 | CSS z-index of the widget |

Theme customization

Pass a ThemeOverride object to fine-tune colors:

<FlintWidget
  projectKey="..."
  serverUrl="..."
  theme={{
    background: "#0f0f0f",
    accent: "#6366f1",
    text: "#f5f5f5",
    border: "#2a2a2a",
  }}
/>

Severity levels

| Level | Meaning | |-------|---------| | P1 | Critical — system down | | P2 | High — core feature broken | | P3 | Medium — noticeable but workable | | P4 | Low — cosmetic or improvement |

Error monitoring

When you initialize the SDK, uncaught errors and unhandled promise rejections are captured automatically and grouped by fingerprint on the server. They show up in the admin's Errors page with occurrence trends, breadcrumbs (recent console logs + failed requests), and resolve/ignore triage.

import { Flint } from "@diegotsi/flint-react"

Flint.init({
  projectKey: "your-project-api-key",
  serverUrl: "https://your-flint-server.com",
  release: "v1.2.3", // enables regression detection and source maps
})

Capture is on by default and storm-safe: per-error throttling (10/min), in-batch dedup, a per-page cap, secret redaction, and a built-in ignore list (Script error., ResizeObserver noise, browser-extension frames). Events are flushed in batches and via sendBeacon on page unload.

| Option | Default | Description | |--------|---------|-------------| | enableErrorMonitoring | true | Turn automatic capture off entirely | | errorMonitoring.sampleRate | 1.0 | Fraction of captured errors to report (0–1) | | errorMonitoring.ignoreErrors | — | (string \| RegExp)[] matched against the message; matches are dropped | | errorMonitoring.beforeSend | — | (event) => event \| null — scrub fields or drop the event |

Server-side, projects can also define ignore rules (Errors page → "Ignore rules") that drop matching events at ingest.

Source maps

Errors arrive with minified stacks. Upload each bundle's source map after a deploy and the admin shows the original frames (with a raw toggle):

curl -X POST -H "X-Project-Key: $FLINT_KEY" \
  --data-binary @dist/assets/index-9f3a.js.map \
  "https://your-flint-server.com/api/v1/sourcemaps?release=v1.2.3&file=index-9f3a.js"

release must match the value passed to Flint.init; file is the bundle's basename, which is how stack frames are matched to their map.

Development

# Watch mode
bun run dev

# Type-check
bun run typecheck

# Build
bun run build