Add a feedback widget to a Next.js application through the shared layout so reviewers can report problems across routes. Annot8 uses a hosted script, with no React package to install. The important checks are script placement, preview host configuration, client-side navigation, and whether the captured evidence describes the state that failed.
Load the script from the shared Next.js layout
With the App Router, put next/script in the root app/layout.tsx or the shared layout for the entire review scope. Use afterInteractive so the review tool does not need to block the initial application render. With the Pages Router, use pages/_app.tsx. Copy the project key and backend URL from the generated Annot8 snippet; the example below shows where those public configuration values belong.
import Script from "next/script";
// Inside the shared layout, alongside your page content:
<Script
src="https://www.annot8.app/widget.js"
data-project-id={process.env.NEXT_PUBLIC_ANNOT8_PROJECT_ID}
data-convex-url={process.env.NEXT_PUBLIC_ANNOT8_CONVEX_URL}
strategy="afterInteractive"
/>These public variables identify the widget project and its backend. Never put a Convex deploy key, Clerk secret, or integration secret into browser-visible variables. For a plain React application, place the generated script in the shared HTML document rather than adding an effect that appends another script every time a route component mounts.
Configure preview hosts and production visibility separately
List the hosts the review actually uses: localhost, a stable staging domain, and any preview deployment hostname. Configure allowed domains and environment patterns deliberately rather than allowing unrelated hosts. A preview URL changes independently of a route, so verify a new preview before sending it to the client.
Annot8 hides the panel on production hosts unless Show widget in production is enabled. Keep that setting aligned with the intended audience. A site can have the correct script and backend URL while the launcher is hidden by environment configuration. If you set a Content Security Policy, follow the documented script, connection, frame, and image allowances; do not disable the policy to make a widget load.
Test route transitions, loading states, and authenticated journeys
- Open a deep link directly, submit feedback, and verify the report’s URL.
- Navigate with a Next.js Link, then report a second issue on the destination page.
- Use browser back and forward navigation and check that the launcher and pinned report still refer to the right page.
- Test a loading, empty, or error state with synthetic data and capture the state that needs correction.
- Repeat the relevant journey with a non-admin test account and at the reported viewport.
A guest feedback link does not bypass your application’s authentication. Reviewers still need authorized access to the page being tested. Include the account role and starting conditions in the report without sharing credentials. For transient UI, add the action sequence and expected outcome so a screenshot is not the only explanation of what failed.
Understand what the browser can capture
Annot8 can attach page and browser context, a selected element, screenshots, recent console errors, and failed network requests. Browser capture is evidence, not a complete application trace: canvas-based screenshots may differ from the rendered page, and browser security boundaries can limit what is visible inside external frames. Reproduce an issue with the original page state when the screenshot alone is ambiguous.
On paid plans, the reporter can initiate a screen recording to demonstrate a sequence and send reports to supported trackers. Treat tracker delivery as a separate verification step; resolving the external issue does not automatically close the Annot8 thread. Analytics also has a separate opt-in: both the project setting and the page’s consent signal must be enabled.
