Supadesk
Start free

How to add Supadesk to Next.js

Next.js sites can use the App Router or the Pages Router. This guide shows you how to add the Supadesk AI chat widget with next/script, so the widget loads once and stays available as visitors move between routes.

Before you start

  1. In Supadesk, open your agent and click Chat Widget.
  2. Click Copy Embed Code.
  3. (Recommended) Add your production Next.js site URL to Allowed Origins — e.g. https://yoursite.com.

Install with App Router

Use this path if your project has an app directory.

  1. Open app/layout.tsx or app/layout.jsx.
  2. Import Script from next/script.
  3. Add your Supadesk script after {children} in the root layout.
  4. Save the file and deploy your app.
import Script from 'next/script'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="YOUR_SUPADESK_SCRIPT_URL"
          strategy="afterInteractive"
        />
      </body>
    </html>
  )
}

If your copied Supadesk embed code includes an inline configuration snippet, keep that snippet exactly as provided by Supadesk and place it near the Script component.

Install with Pages Router

Use this path if your project has a pages directory and no root app directory.

  1. Open pages/_app.tsx or pages/_app.jsx.
  2. Import Script from next/script.
  3. Add your Supadesk script next to the page component.
  4. Save the file and deploy your app.
import type { AppProps } from 'next/app'
import Script from 'next/script'

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="YOUR_SUPADESK_SCRIPT_URL"
        strategy="afterInteractive"
      />
    </>
  )
}

Next.js tip

Use strategy="afterInteractive" for the Supadesk widget. It lets your page hydrate first, then loads the chat widget without requiring visitors to refresh when they navigate between routes.

Check it works

Run your app locally or open the deployed site in a private browser window. The chat bubble should appear in the bottom-right corner after the page becomes interactive.

Troubleshooting

  • Widget missing: Confirm the script URL and any inline configuration from Supadesk were copied exactly.
  • Widget only appears after refresh: Make sure the script is in app/layout or pages/_app, not inside a single page component.
  • Widget blocked: Add your exact deployed origin (including https://) to Allowed Origins in Supadesk.
  • Localhost works but production does not: Add your production domain to Allowed Origins and redeploy after the script change.

FAQ

Should I install Supadesk in app/layout.tsx or a page component?

Install Supadesk in app/layout.tsx for App Router projects. The root layout is shared by all routes, so the chat widget loads once and remains available throughout the site.

Where do I install Supadesk in a Pages Router project?

Install Supadesk in pages/_app.tsx or pages/_app.jsx. That file wraps every page in a Pages Router app, which makes it the right place for a site-wide chat widget.

Can I paste the raw script tag directly into a React component?

Use next/script instead of a raw <script> tag. It is the Next.js component designed for third-party scripts and keeps the widget loading reliably across client-side navigation.

More install guides

Don't have a Supadesk account?

Start free, create your agent, then come back to this guide to install the widget on your site.

Start free