React and Next.js tutorial

How to add a bug-reporting widget to React and Next.js

Install and initialize the PinWid bug-reporting widget in React or Next.js, configure allowed origins, and verify the first contextual report.

By Khikmat TuraevNovember 8, 2026 10 min read

A useful bug-reporting widget needs to run in the browser, initialize once and stay outside server rendering. In Next.js App Router that means placing initialization behind a Client Component. In a client-rendered React app, initialize from the application entry point or a small effect component.

The PinWid client widget is framework-neutral. The same package can be used in React, Next.js, Vite and other browser applications; the main difference is where the browser-only initialization belongs.

What you will learn

Install the official @pinwid/client-widget package.
Initialize only in the browser and only once.
Configure the exact staging and production origins in PinWid.
Send a test report and inspect visual plus technical context before release.

1. Create the project and allowed origins

Create a PinWid project, add an environment and copy its public keys. Add every origin where the widget should load, including the protocol and port for local development. Keep staging and production distinct so reports arrive with the correct environment context.

Public widget keys identify the project; they are not server secrets. Do not place private API credentials in browser code. Store public configuration in your framework's public environment variables and keep the allowed-origin list narrow.

Local: http://localhost:3000
Staging: https://staging.example.com
Production: https://app.example.com

2. Install the client package

Add the package with the package manager already used by your application. Pin the version through your lockfile and test updates in staging before promoting them to production.

Terminal

pnpm add @pinwid/client-widget
# or: npm install @pinwid/client-widget

3. Initialize it in a Next.js Client Component

Create a small component that runs after the browser mounts. Render it once in the root layout or in the authenticated product shell, depending on where users should be able to report. The effect cleanup should destroy the client when supported, which prevents duplicate launchers during development and route transitions.

Use NEXT_PUBLIC_ variables only for the public project configuration. If your application renders sensitive routes where reporting is inappropriate, mount the component in a narrower layout or disable capture for those paths.

app/PinWidFeedback.tsx

"use client";

import { useEffect } from "react";
import { init } from "@pinwid/client-widget";

export function PinWidFeedback() {
    useEffect(() => {
        const client = init({
            publicKey: process.env.NEXT_PUBLIC_PINWID_PUBLIC_KEY!,
            environmentKey: process.env.NEXT_PUBLIC_PINWID_ENVIRONMENT_KEY!,
        });

        return () => client?.destroy?.();
    }, []);

    return null;
}

4. Initialize it in a client-rendered React app

For Vite or another client-rendered React setup, the same component pattern works. Replace the environment variable access with the convention used by your build tool. With Vite, public variables are read from import.meta.env and normally use the VITE_ prefix.

src/PinWidFeedback.tsx

import { useEffect } from "react";
import { init } from "@pinwid/client-widget";

export function PinWidFeedback() {
    useEffect(() => {
        const client = init({
            publicKey: import.meta.env.VITE_PINWID_PUBLIC_KEY,
            environmentKey: import.meta.env.VITE_PINWID_ENVIRONMENT_KEY,
        });

        return () => client?.destroy?.();
    }, []);

    return null;
}

5. Verify the first report before shipping

Open the application on an allowed origin and submit a report from a page with a known test issue. Confirm that the launcher works on mobile, does not cover critical controls and remains visually isolated from your application styles.

Then inspect the report in PinWid. Verify the screenshot, page URL, environment, browser details and enabled diagnostics. Test privacy controls with realistic form fields before enabling optional session capture in production.

One launcher appears after navigation and hot reload.
The exact environment and URL are attached.
The screenshot and annotation match the selected area.
Sensitive values are masked or excluded.
The report can be assigned and moved through review.

Real PinWid product demo

Try the reporting workflow before adding the package

The interactive PinWid demo shows the report your React or Next.js users create and the triage context developers receive.

Open interactive demo View the React widget product page

Report contextReady

Framework-neutral TypeScript client

Isolated reporter UI

Visual, browser and runtime evidence

FAQ

Common questions

Does the PinWid widget work with Next.js App Router?

Yes. Initialize it from a Client Component after mount and render that component once in the layout where reporting should be available.

Are PinWid project keys safe in browser code?

The widget uses public project and environment identifiers. They are not private server credentials, but allowed origins should still be configured precisely.

Put the workflow into practice

Capture your first actionable report.

Create a PinWid workspace, install the widget on one environment and test the reporting flow with a real issue.

Start free