> ## Documentation Index
> Fetch the complete documentation index at: https://www.pagent.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js

> Add pagent to a Next.js site, with the App Router or the Pages Router.

Add pagent as a plain `<script>` tag in the document `<head>`, with `data-await-hydration="true"`. pagent recognizes Next.js hydration in both routers, and follows client-side navigation on its own.

> [!WARNING]
>
> Don't use `next/script`, not even with `strategy="beforeInteractive"`. Next.js adds those scripts with its own JavaScript, so they don't block the page from showing. The page can show before pagent runs, and visitors see the original flash.

## App Router

Add the tag to the `<head>` of your root layout:

```tsx app/layout.tsx theme={"dark"}
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        {/* eslint-disable-next-line @next/next/no-sync-scripts -- pagent must run before the page shows */}
        <script
          src="https://cdn.pagent.ai/js/sdk.js"
          data-client-key="YOUR_CLIENT_KEY"
          data-await-hydration="true"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

## Pages Router

Add the tag to the `<Head>` of your custom document:

```tsx pages/_document.tsx theme={"dark"}
import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        {/* eslint-disable-next-line @next/next/no-sync-scripts -- pagent must run before the page shows */}
        <script
          src="https://cdn.pagent.ai/js/sdk.js"
          data-client-key="YOUR_CLIENT_KEY"
          data-await-hydration="true"
        />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}
```

## Recommendations

* **Keep `data-await-hydration="true"`.** Without it, hydration can undo a variant right after pagent applied it.
* **Slow pages:** if your pages hydrate slowly, raise the wait with `data-hydration-timeout="800"`. Try it first on a preview link with `?pagent_hydration_timeout=800`.
* **Streaming and Suspense:** pagent waits for Suspense boundaries that have already arrived, not for ones that are still streaming. Test variants on content inside late Suspense boundaries with a preview link.
* **Navigation:** route changes with `<Link>` and `router.push` are tracked automatically. Don't call `navigate` yourself, or the page view counts twice.

See [Frameworks](https://www.pagent.ai/docs/install/frameworks.md) for the shared rules and the Content Security Policy.

## Check it worked

1. Deploy, then open your site in a private browser window.
2. Back in pagent, click **Check connection** in the install step.
3. Open a test's preview link and check that the variant shows and stays after the page has finished loading.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.