My Dashboard

Install on Next.js

Load PopupNeko site-wide with Next.js Script in either the App Router or Pages Router.

On this page
  1. App Router setup
  2. Pages Router setup
  3. Client-side navigation
  4. Deploy and check

Use Next.js's built-in Script component to load PopupNeko once for the whole application. Copy the project ID from Install Script in PopupNeko first.

App Router setup

For an App Router application, add Script to the root layout. Keep your metadata, providers, fonts, and other layout content intact.

app/layout.tsx
import type { ReactNode } from "react";
import Script from "next/script";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
      <Script
        src="https://popupneko.com/script/popupneko.js"
        data-project-id="YOUR_PROJECT_ID"
        strategy="beforeInteractive"
      />
    </html>
  );
}

The beforeInteractive strategy makes Next.js include the script in the initial server-rendered HTML and load it before hydration. Next.js moves a beforeInteractive script into the document head automatically, regardless of where the component appears in the root layout. This also lets PopupNeko's HTML-based installation verifier see the script URL and project ID.

Do not change this example to afterInteractive if you rely on Verify Connection. That strategy injects the script client-side, while the verifier reads the returned HTML without running your application's JavaScript. See Next.js's Script documentation for strategy details.

Pages Router setup

If your application uses the Pages Router, add Script to your custom document. Preserve the standard Html, Head, Main, and NextScript structure.

pages/_document.tsx
import { Html, Head, Main, NextScript } from "next/document";
import Script from "next/script";

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        <Main />
        <NextScript />
        <Script
          src="https://popupneko.com/script/popupneko.js"
          data-project-id="YOUR_PROJECT_ID"
          strategy="beforeInteractive"
        />
      </body>
    </Html>
  );
}

For the Pages Router, Next.js requires a beforeInteractive script to be declared in pages/_document.tsx. It is still emitted in the document head. Do not add a second copy to _app, individual pages, or another custom head component.

Client-side navigation

PopupNeko handles History API pathname changes, including back/forward navigation. You do not need a pathname effect to reinstall it. On each distinct pathname, it applies your saved targeting rules and loads eligible activity.

Query-string or hash-only navigation does not start a new popup cycle. Target actual URL paths rather than React component names or route-group folder names.

Deploy and check

Deploy the layout change, visit your production site, and run Verify Connection on the Install Script page. If you have multiple root layouts, include the embed in each layout that serves pages where popups should be available, with only one copy per document.

Check page targeting, live access, and eligible events if the script is detected but no popup appears. Register online preview hostnames in Allowed Domains; arbitrary preview domains are not automatically authorized.