# add live chat to a next.js site
Add Spookat's chat to a Next.js app, in the app router or the pages router, with its look and an optional logged-in user, and verify it makes 0 requests to our API before a click.
2026-11-04 ยท Kuba
Live chat in Next.js is one script tag in the root layout. This guide shows where it goes in the app router and the pages router, how to pass the widget's look and the logged-in user without breaking the load order, what to add to a Content Security Policy, and how to check the result in a production build.
## the short version
In the app router, add the tag to `app/layout.tsx`, inside ``:
```tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
Replace `YOUR_SITE_KEY` with the key from the dashboard's install page. That's the whole install when the look lives in the dashboard, which is the default. The rest of this guide is for when you want more control. If you're starting from zero, the [pillar guide](/blog/add-live-chat-to-your-website/) covers the account side.
## why the root layout
The root layout wraps every route and stays mounted while the user navigates. The launcher attaches itself to the page once. Client-side navigation doesn't reload the page, so it doesn't reload the launcher either, and a visitor can keep a conversation open while they click around.
Put the tag in a page component and the chat only exists on that page. Put it in a component that renders on several pages and you get duplicates on hard reloads (the launcher ignores its own second copy, but it's still a wasted request).
## with next/script
`next/script` is the Next.js way to load third-party scripts, and it works fine here:
```tsx
import Script from "next/script";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
`afterInteractive` loads the launcher right after hydration. `lazyOnload` waits until the browser is idle, which pushes the button's appearance a little later on slow phones. Either is fine for a 2 kb launcher; `afterInteractive` shows the button sooner. Don't use `beforeInteractive` for the launcher: it would compete with your own code for nothing.
## setting the look in code
The look you publish in the dashboard travels inside the launcher. If you'd rather keep it in the repo, set `window.Spookat` before the launcher runs. The page's config wins over the dashboard's.
The load order matters: the config has to exist when the launcher executes. With `next/script`, give the config `beforeInteractive` (allowed in the root layout) and the launcher `afterInteractive`:
```tsx
import Script from "next/script";
const spookat = { style: "clean", font: "system", accent: "#2F6FEB", side: "right" };
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
`beforeInteractive` scripts run before hydration, `afterInteractive` ones after it, so the order is guaranteed. The keys are the same as anywhere else: `style` (one of 8), `font`, `accent`, `side`, `greeting`, `label`, `lang`. The [docs](/docs/) list them all.
## the pages router
In the pages router, the shared wrapper is `pages/_app.tsx`:
```tsx
import type { AppProps } from "next/app";
import Script from "next/script";
export default function App({ Component, pageProps }: AppProps) {
return (
<>
);
}
```
For a config, `beforeInteractive` scripts belong in `pages/_document.tsx` in the pages router. Put the `window.Spookat` script there, inside ``, with the same `id` and `strategy` as above, and keep the launcher in `_app.tsx`.
## the logged-in user
On pro and above, you can tell the chat who is signed in. Your team then sees `logged in as 42` on the Slack card, and webhooks, the export and your agent's `read_convo` carry the id. The id is signed with a secret that only your server knows, so nobody can pretend to be someone else.
Make the identity secret on the dashboard's install page, put it in an environment variable, and sign on the server. In the app router, the root layout is a server component, which makes this simple:
```tsx
import { createHmac } from "node:crypto";
import Script from "next/script";
import { getSession } from "@/lib/auth"; // yours
const sign = (id: string) => createHmac("sha256", process.env.SPOOKAT_IDENTITY_SECRET!).update(id).digest("hex");
export default async function RootLayout({ children }: { children: React.ReactNode }) {
const session = await getSession();
const user = session ? { id: String(session.userId), sig: sign(String(session.userId)) } : undefined;
return (
{children}
{user && (
)}
);
}
```
Never compute the signature in a client component: the secret would ship to the browser. A missing or wrong signature isn't an error; the chat simply doesn't say who it is. Reading the session in the root layout makes every page render per request, so if your layout is static today, weigh that before you add it.
## content security policy
If your app sends a `Content-Security-Policy` header, the widget needs:
- `script-src` and `style-src`: `https://cdn.spookat.com`
- `font-src`: `https://cdn.spookat.com`, if you picked a hosted font
- `connect-src`: `wss://api.spookat.com`, for the chat connection after a click
- `img-src`: `data:`, for logos and teammate pictures
- `style-src`: the launcher injects one small `