React / Next.js

Add Inclusify to your React or Next.js application using the Script component or head injection.

Register the domain first

Add your domain in the Inclusify panel before you paste the script tag. Bundles are built per registered domain, and an unregistered one fails silently: the script URL still returns HTTP 200, but what it serves is a single console.log saying the domain is not registered. There is no error to find and no widget appears.

Next.js (App Router)

Use the Next.js Script component in your root layout, so it mounts once and survives client-side navigation:

app/layout.tsx
import Script from 'next/script'

export default function RootLayout({
    children,
}: {
    children: React.ReactNode
}) {
    return (
        <html lang="en">
            <body>
                {children}
                <Script
                    src="https://app.inclusifyapp.com/w/YOUR-DOMAIN.com.js"
                    strategy="afterInteractive"
                />
            </body>
        </html>
    )
}

afterInteractive is the default and the right choice here: Next.js injects the tag client-side once hydration starts, so the widget loads promptly without sitting on the critical path. It also means the tag is not in the server-rendered HTML - check the loaded DOM or the network tab, not View Source.

Next.js (Pages Router)

Add to your custom _app.js:

pages/_app.js
import Script from 'next/script'

export default function MyApp({ Component, pageProps }) {
    return (
        <>
            <Component {...pageProps} />
            <Script
                src="https://app.inclusifyapp.com/w/YOUR-DOMAIN.com.js"
                strategy="afterInteractive"
            />
        </>
    )
}

React (Vite, CRA)

Add the script to your index.html:

index.html
<script src="https://app.inclusifyapp.com/w/YOUR-DOMAIN.com.js" async></script>

Add before the closing </body> tag.

Notes

  • • Works with all React frameworks (Next.js, Remix, Gatsby, Vite, CRA)
  • • Safe under SSR - the tag is inert markup on the server and the widget only executes in the browser, so it cannot cause a hydration mismatch
  • • No React component and no npm package - the widget initializes itself from the script tag and exposes no React API

Verify the installation

  1. Run a production build rather than the dev server: next/script behaves differently under development's Fast Refresh.
  2. Do not use View Source: with the afterInteractive strategy Next injects the tag client-side, so it is absent from the server-rendered HTML on a correct install. Look for the tag in the Elements panel instead, or filter the Network tab for "w/" and confirm the bundle request to app.inclusifyapp.com returns 200.
  3. Navigate between routes client-side and confirm the widget stays mounted — it lives outside the React root and should not be torn down.

Widget bundles are served from a CDN and cached for a few hours. If you changed widget settings in the panel and the site still shows the old configuration, wait for the cache to expire or load the script URL directly with a cache-busting query string (`?v=2`) to confirm the new version is being served.

Troubleshooting React / Next.js installs

The script loads twice in development.
React StrictMode double-invokes effects in development only. Check a production build before treating it as a bug.
The browser blocks the request with a CSP error.
Add https://app.inclusifyapp.com to script-src and connect-src in the Content-Security-Policy header you set in next.config.js or middleware.
The widget disappears after a client-side route change.
The script was mounted inside a page component that unmounts on navigation. Move it to the root layout (App Router) or _app (Pages Router) so it mounts once.
Nothing loads in a static export.
A static export comes from `output: "export"` in next.config.js plus a normal next build - the standalone `next export` command was removed in Next.js 14. Do not judge it by the HTML in out/: on the afterInteractive strategy the tag is injected client-side and will not be in that file even when the install is correct. Load an exported page in a browser and check the request to app.inclusifyapp.com instead.

React / Next.js questions

Which next/script strategy should I use?
afterInteractive. The widget does not need to run before hydration, and beforeInteractive would put it on the critical path. lazyOnload also works if you want it to wait for the load event.
Do I need a React component or a wrapper package?
No. The widget initialises itself from the script tag and does not expose or require a React API.
Does it work with Remix, Gatsby, Vite or Create React App?
Yes. Any of them can render a plain script tag in the document shell — index.html for Vite and CRA, the root route document for Remix.
Is it safe with server-side rendering?
Yes. The tag is inert markup on the server and the widget only executes in the browser, so it does not affect the SSR pass or cause hydration mismatches.

Related