Install guide · Next.js

Add the Quackback widget to Next.js

In the App Router, the widget runs in a small client component that sits in your root layout. A route handler signs a token for the signed-in user, so the signing secret never leaves the server.

Get your widget snippet

14-day Pro trial, no card needed
Your workspace URL and snippet, ready to copy
The widget is on every plan, including Free

Start free trial Read the install docs

The widget your customers see inside your app.

Your team’s viewYour customers’ view

Feedback

Review

Status

Board

Install the widget in Next.js

First, in Quackback, open Settings, then Widget, and turn on Show on your website. Until it's on, the snippet loads but the launcher stays hidden. Every snippet uses your-workspace.quackback.io as a placeholder. Swap in your workspace URL, or your custom domain, from Settings, under Widget, then Install.

Read the full install docs

Install the package

Add @quackback/widget. Next.js 15 and later run React 19, which the React hooks need.

Terminal

npm install @quackback/widget

Create a client component

The widget needs the browser, so the component starts with "use client". It renders nothing. Put your workspace URL in a NEXT_PUBLIC_ variable so the browser can read it.

app/quackback-widget.tsx

"use client";

import { useQuackbackInit } from "@quackback/widget/react";

export function QuackbackWidget() {
  useQuackbackInit({
    instanceUrl: process.env.NEXT_PUBLIC_QUACKBACK_URL!,
  });
  return null;
}

// .env.local
// NEXT_PUBLIC_QUACKBACK_URL=https://your-workspace.quackback.io

Add it to the root layout

Render it once in app/layout.tsx so it loads on every page and survives client-side navigation.

app/layout.tsx

import { QuackbackWidget } from "./quackback-widget";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <QuackbackWidget />
      </body>
    </html>
  );
}

Identify signed-in users

A route handler reads your session and signs a five-minute token. The client component fetches it once and passes it to identify.

How identify works

Add a route handler that signs the token

Copy the signing secret from Settings, under Widget, then Install, into WIDGET_SIGNING_SECRET. No NEXT_PUBLIC_ prefix, so it stays on the server. Use whatever session helper your auth library gives you.

app/api/widget-sso/route.ts

import { SignJWT } from "jose";
import { getCurrentUser } from "@/lib/auth"; // your session helper

const secret = new TextEncoder().encode(process.env.WIDGET_SIGNING_SECRET);

export async function GET() {
  const user = await getCurrentUser();
  if (!user) return new Response("Unauthorized", { status: 401 });

  const ssoToken = await new SignJWT({
    sub: String(user.id), // stable user id, never the email
    email: user.email,
    name: user.name,
  })
    .setProtectedHeader({ alg: "HS256" })
    .setExpirationTime("5m")
    .sign(secret);

  return Response.json({ ssoToken });
}

Identify from the client component

Fetch the token once per page load. A 401 means nobody is signed in, and the widget stays anonymous. Call Quackback.logout() from your sign-out action.

app/quackback-widget.tsx

"use client";

import { useEffect, useState } from "react";
import { useQuackbackInit } from "@quackback/widget/react";

export function QuackbackWidget() {
  const [ssoToken, setSsoToken] = useState<string>();

  useEffect(() => {
    fetch("/api/widget-sso")
      .then((res) => (res.ok ? res.json() : null))
      .then((data) => data && setSsoToken(data.ssoToken));
  }, []);

  useQuackbackInit({
    instanceUrl: process.env.NEXT_PUBLIC_QUACKBACK_URL!,
    identity: ssoToken ? { ssoToken } : undefined,
  });

  return null;
}

Good to know on Next.js

Widget events and methods

Server components can't init itImporting the package on the server is safe, but init touches the DOM. Keep the hook in a "use client" file and render that from your layout.

Layout, not pageA layout persists across navigation, so the widget inits once. In a page component it would tear down and boot again on every route change.

Pages RouterOn the Pages Router, call useQuackbackInit inside pages/_app.tsx. Put the token route in pages/api/widget-sso.ts.

Content Security PolicyIf you set a CSP, allow your workspace URL in frame-src and connect-src. The launcher injects a small style element, so style-src must allow inline styles.

Common questions

Can I use next/script instead of the npm package?

Yes. The script-tag snippet from Settings works in a <Script> with the afterInteractive strategy. The npm package is easier to type-check and lets you use the React hooks.

Does identify run on every navigation?

No. The component lives in the root layout, so it fetches the token once per full page load. The widget keeps its own session after a successful identify.

Will the widget slow down my site?

The script loads asynchronously, and the panel loads in an iframe when the browser is idle, so it stays off your critical path. Its theme and settings come from your workspace, so changing them needs no redeploy.

Is the Quackback widget free?

Yes. The widget is on every plan, including Free, with feedback, live chat, help articles and your changelog inside it. Every signup starts with a 14-day Pro trial.

Have another question? Talk to the team.

Put feedback inside your Next.js app

Start free trial All install guides