@traceitx/react
v0.6.3
Published
React SDK for TraceItX — AI-ready in-app bug reporting with screenshots, annotation, session replay, breadcrumbs, and crash capture.
Maintainers
traceitxdevReadme
@traceitx/react
React (web) SDK for TraceItX — AI-ready bug reporting embedded in your app.
Apache-2.0 · React 18 || 19 · ESM-only · Node 20+
Install
pnpm add @traceitx/react
# or
npm install @traceitx/reactOptional but recommended: install the displayName preservation plugin so component names survive minification:
# Babel users (Webpack / CRA / Next.js with Babel config)
pnpm add -D @traceitx/babel-plugin-displayname
# SWC users (Next.js default since 12+)
pnpm add -D @traceitx/swc-plugin-displaynameQuickstart
Wrap your app once. The Provider mounts the floating bubble, registers the hotkey, and owns the reporter modal lifecycle.
// app/layout.tsx (Next.js app router)
import { TraceItXProvider } from '@traceitx/react';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
<TraceItXProvider config={{ apiKey: 'txx_live_xxxxxxxxxxxxxxxx' }}>
{children}
</TraceItXProvider>
</body>
</html>
);
}Open the reporter programmatically from anywhere:
'use client';
import { useTraceItX } from '@traceitx/react';
export function HelpButton() {
const { open } = useTraceItX();
return <button onClick={open}>Report a bug</button>;
}Triggers
By default the SDK installs:
- Hotkey
Cmd/Ctrl+Shift+B(TRIG-03) — rebind withconfig.hotkey = { binding: 'Mod+Shift+R' }, or disable withconfig.hotkey = false
Mod resolves to Cmd on macOS and Ctrl elsewhere.
A visible trigger (bubble, menu item, etc.) is the host app's responsibility — call useTraceItX().open() from your own button to bring up the reporter.
Strict-CSP environments
If your app sets a strict CSP (script-src 'self' 'nonce-...'), thread the nonce into the SDK so screenshot capture's dynamically-injected styles are accepted:
// Next.js: read the nonce from headers() in your layout
import { headers } from 'next/headers';
export default async function RootLayout({ children }: { children: React.ReactNode }) {
const nonce = (await headers()).get('x-nonce') ?? '';
return (
<TraceItXProvider config={{ apiKey: 'txx_live_xxxxxxxxxxxxxxxx', cspNonce: nonce }}>
{children}
</TraceItXProvider>
);
}Marking sensitive content (PRIV-02)
Three equivalent surfaces — pick whichever fits your codebase:
import { Sensitive, useTraceItX } from '@traceitx/react';
import { useEffect, useRef } from 'react';
// 1. Component wrapper
<Sensitive><CreditCardNumber /></Sensitive>
// 2. data-attribute (works on any DOM element)
<div data-traceitx-sensitive>{value}</div>
// 3. Ref hook
function MyField({ value }: { value: string }) {
const ref = useRef<HTMLDivElement>(null);
const { markSensitive } = useTraceItX();
useEffect(() => {
if (ref.current) markSensitive(ref);
}, [markSensitive]);
return <div ref={ref}>{value}</div>;
}All three resolve to the same internal sensitive-rect registry; pixels under those rects are blanked at capture time before the screenshot bytes leave the device.
Bundling notes
The SDK is ESM-only. Some Next.js + monorepo setups need to transpile workspace packages:
// next.config.ts
transpilePackages: ['@traceitx/react', '@traceitx/sdk-core', '@traceitx/protocol'],The always-loaded entry measures ~136 KB gzip (pnpm size-limit, budget 240 KB). The heavy capture and annotation dependencies — rrweb, react-konva, bippy, modern-screenshot, html-to-image — are lazy-imported and are not in that number; they load only when the reporter is actually opened.
Example
See examples/react-web/ for a Next.js dogfood project covering both the strict-CSP fixture and the standard SSR fixture.