Add a bug report widget to a Next.js app

One next/script tag. It loads after your page is interactive, renders in a Shadow DOM so it doesn't touch your styles, and works with the App Router and the Pages Router.

1Create a project

In the dashboard create a project and copy its key from Install & settings. Add your production domain and your preview domains to Allowed origins, for example https://*.vercel.app. Local development (http://localhost:3000) needs its own line if you want to test there.

2Add the script

App Router, in app/layout.tsx:

import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script src="https://uups.dev/widget.js" data-project-key="pk_…" strategy="afterInteractive" />
      </body>
    </html>
  );
}

Pages Router, in pages/_app.tsx:

import Script from "next/script";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script src="https://uups.dev/widget.js" data-project-key="pk_…" strategy="afterInteractive" />
    </>
  );
}

Using Cursor or Claude Code? The Install with AI prompt in the project settings does the same.

3Identify signed-in users (optional)

Sign the user id on the server with the project's identity secret, so reports are marked verified and nobody can send feedback in someone else's name. Put the secret in UUPS_IDENTITY_SECRET; never expose it to the browser.

// app/feedback-user.tsx
"use client";
import { useEffect } from "react";

type Reporter = { id: string; email?: string; name?: string; signature: string };

export function FeedbackUser({ user }: { user: Reporter | null }) {
  useEffect(() => {
    const w = window as any;
    w.FeedbackWidget = w.FeedbackWidget || { q: [] };
    if (w.FeedbackWidget.q) w.FeedbackWidget.q.push(["identify", user]);
    else w.FeedbackWidget.identify(user);
  }, [user]);
  return null;
}
// app/layout.tsx (server component)
import { createHmac } from "node:crypto";
import Script from "next/script";
import { FeedbackUser } from "./feedback-user";

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const user = await getCurrentUser(); // your auth
  const reporter = user && {
    id: user.id,
    email: user.email,
    name: user.name,
    signature: createHmac("sha256", process.env.UUPS_IDENTITY_SECRET!).update(user.id).digest("hex"),
  };
  return (
    <html lang="en">
      <body>
        {children}
        <Script src="https://uups.dev/widget.js" data-project-key="pk_…" strategy="afterInteractive" />
        <FeedbackUser user={reporter} />
      </body>
    </html>
  );
}

Calls made before the script has loaded are queued and run once it's ready.

4Content Security Policy

If your app sends a CSP header, allow the widget script, its API and the direct upload of recordings:

script-src  ... https://uups.dev;
connect-src ... https://uups.dev https://*.r2.cloudflarestorage.com;

Screen recording also needs the browser's screen-capture permission. If you send a Permissions-Policy header, don't set display-capture=().

5Open it from your own button (optional)

Turn off Show floating button in the project settings and open the widget from your help menu:

<button onClick={() => (window as any).FeedbackWidget?.open({ type: "bug" })}>Report a bug</button>

Stuck?

  • No button on the page: check that the script is on the live site (view the page source and search for widget.js), and that "Show floating button" is on in the project settings.
  • "This website is not allowed" when sending: add the site's address to Allowed origins in the project settings, exactly as it appears in the address bar (scheme and domain, no path).
  • No screen recording option: recording works in desktop Chrome, Edge, Firefox and Safari. On phones and tablets people can still send text and screenshots.
  • Still nothing? Email hello@uups.dev with the page address.