Add Aliendesk to Next.js and React
Install guide
What you need
- An Aliendesk account
- Your brand key from the install snippet
- A Next.js or React app you can deploy
Install it
Step 1: Copy your snippet
In Aliendesk, open Settings → Live chat widget and copy the script tag under Install. It already contains your brand key.
Step 2: Next.js: add it to your root layout
With the App Router, add the widget with
next/scriptinapp/layout.tsxso it loads once and stays loaded as visitors move between pages.strategy="lazyOnload"waits for browser idle time, so it never competes with your page. With the Pages Router, put the same<Script>inpages/_app.tsx.app/layout.tsximport Script from 'next/script'; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="en"> <body> {children} <Script src="https://widget.aliendesk.io/loader.js" data-brand="YOUR_BRAND_KEY" data-api="https://app.aliendesk.io" strategy="lazyOnload" /> </body> </html> ); }Step 3: React: add it to index.html
For a single-page React app (for example with Vite), paste the snippet just before
</body>inindex.html. It stays loaded as your router changes pages.index.html<script src="https://widget.aliendesk.io/loader.js" data-brand="YOUR_BRAND_KEY" data-api="https://app.aliendesk.io" async></script>Step 4: Tell it who is signed in (optional)
Call
AlienDesk.identify()after login with the user’s id, email and auserHashsigned on your server, so your team and the AI see their details. The developer docs show the full call.Step 5: Allow your domain
Back in Settings → Live chat widget, add your website's domain under Allowed domains.
localhostalways works while you develop. The widget then only runs on your own sites.
Check it works
- Open your website in a private window. The chat launcher appears in the corner once the page has finished loading.
- Open it and ask something your website answers. The reply shows the page it came from.
- In Aliendesk, open your inbox. The conversation is already there.
Not ready to touch your site yet? Use Open test page in Settings → Live chat widget to try the widget on a plain page first.
Troubleshooting
- The widget disappears after a client-side navigation
- Load it from the root layout (or
_app.tsx), not from a single page, so it is not removed when the page changes. - The widget doesn't show up
- Open your live site in a private window and wait for the page to finish loading: the widget loads after your page so it never slows it down. Then view the page source and search for
loader.jsto check the snippet made it onto the published page, with your brand key indata-brand. - It works on one domain but not another
- Add every domain the widget runs on, including
www, staging and preview domains, under Allowed domains in Settings → Live chat widget. While you test, you can leave the list empty to allow any site. - Caching or optimisation tools
- Clear your site and CDN cache after adding the snippet. If a plugin or service combines, minifies or delays JavaScript, exclude
widget.aliendesk.io/loader.jsfrom it. - Ad blockers and privacy extensions
- Some browser extensions block chat widgets. Test in a private window with extensions turned off before changing anything else.
Still stuck? Ask in the chat, or email support@aliendesk.io. To pass signed-in users or listen for widget events, read the developer docs.
Platform steps checked against Next.js: how to load and optimize scripts on 18 October 2026. Menus can move; follow the platform's own docs if they differ.

