@matiasparadela/visual-bug-reporter
v0.1.2
Published
Visual bug reporting widget for Next.js. Point at any element, capture console/network/breadcrumbs plus the component's file:line, and file it as a GitHub issue.
Downloads
376
Maintainers
matiasparadelaReadme
@matiasparadela/visual-bug-reporter
Visual bug reporting for Next.js. A QA person, PM or client clicks any element on the running app, writes what's wrong, and you get a GitHub issue containing the component's file and line number plus the console, network and interaction context that led to the bug.
Built to close the loop between "it looks broken" and a ticket a developer can act on without a back-and-forth.
- Dev/staging only. Gated behind a single env flag, zero footprint in production builds.
- No design system coupling. Styles are scoped CSS — no Tailwind, no design tokens, nothing leaks into or out of the host app.
- Pluggable backend. GitHub Issues ships built in; any tracker works via a small interface.
What ends up in the issue
| Captured | Detail |
| ---------------- | ------------------------------------------------------------------------------------ |
| Source location | FellowCard (/src/components/fellow-card.tsx:88) — the component and the exact line |
| Element | Tag, visible label, sanitized props |
| Parent call site | Which component rendered it, and where |
| Page | URL, route, viewport size, commit SHA |
| Breadcrumbs | The last interactions before the report — clicks, submits, changes, navigations |
| Console | Errors and warnings, redacted |
| Network | Failed and slow requests, redacted |
| Reporter | Whoever filed it, plus a severity they pick |
Annotations accumulate in a session, survive reloads, and get filed in one go.
Install
pnpm add -D @matiasparadela/visual-bug-reporter @locator/webpack-loader
pnpm add @radix-ui/react-popover@locator/webpack-loader must be a direct dependency of your app: build loaders
are resolved by name from your node_modules, so a transitive install won't be
found under pnpm.
Quickstart
Three files, then the environment variables.
1. next.config.ts — inject the loader that records where each element came
from.
import { withBugReporter } from '@matiasparadela/visual-bug-reporter/next';
export default withBugReporter({
reactStrictMode: true,
});2. app/layout.tsx — mount the widget. Render it last, inside <body>.
import { BugReporter } from '@matiasparadela/visual-bug-reporter';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
{children}
<BugReporter
enabled={process.env.NEXT_PUBLIC_BUG_REPORTER === '1'}
commitSha={process.env.NEXT_PUBLIC_COMMIT_SHA}
/>
</body>
</html>
);
}3. app/api/bug-reporter/issues/route.ts — the endpoint that files issues.
The GitHub token stays server-side and never reaches the browser.
export { POST } from '@matiasparadela/visual-bug-reporter/next/server';
export const runtime = 'nodejs';4. Environment variables — see docs/ENVIRONMENT.md for the full list and how to create the GitHub token.
Restart the dev server. The loader is wired at build time, so a hot reload will not pick it up. A floating button appears in the corner.
<BugReporter /> props
| Prop | Type | Default | Notes |
| ---------------- | --------------------------------- | ---------------------------- | -------------------------------------------------------------------------- |
| enabled | boolean | — | Required. Renders null when false, and every capture hook no-ops. |
| commitSha | string | 'dev (local)' | Stamped on every report so you know which build it came from. |
| position | 'bottom-right' \| 'bottom-left' | 'bottom-right' | Corner for the floating button. |
| issuesEndpoint | string | '/api/bug-reporter/issues' | Where reports get POSTed. Match it to where you mounted the route. |
| reporter | string | — | Who is reporting, e.g. the logged-in user's email. Goes in the issue body. |
Documentation
| | | | ---------------------------------- | --------------------------------------------------------- | | Integration | Full setup, monorepos, Turborepo, troubleshooting | | Environment | Every variable, and how to create the GitHub token | | Providers | Targeting Linear, Jira or anything else | | Security | Threat model, redaction, why this must never ship to prod |
Requirements
React 19+, Next.js 15+ (App Router). Turbopack and webpack both supported.
License
MIT