Next.js

App Router

The widget needs a browser, so it loads from a client component. Create one provider file and render it from your root layout.

npm i @shopassist/js @shopassist/react

app/providers.tsx

"use client";

import { ShopAssistProvider } from "@shopassist/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ShopAssistProvider config={{ shopDomain: "your-shop.com" }}>
      {children}
    </ShopAssistProvider>
  );
}

app/layout.tsx

import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

The layout itself stays a server component. Only providers.tsx carries the "use client" directive.

Opening the chat from your own button

components/help-button.tsx

"use client";

import { useShopAssist } from "@shopassist/react";

export function HelpButton() {
  const { open } = useShopAssist();
  return <button onClick={() => open()}>Chat with us</button>;
}

open works before the widget has finished loading. The call is held and replayed once the widget is on screen, so you do not have to check first.

Without React bindings

@shopassist/js is safe to import from a server component: every function is a no-op there. If you would rather not add the React package, call it from an effect.

app/shop-assist.tsx

"use client";

import { useEffect } from "react";
import ShopAssist from "@shopassist/js";

export function ShopAssistLoader() {
  useEffect(() => {
    ShopAssist({ shopDomain: "your-shop.com" });
  }, []);
  return null;
}

Pages Router

pages/_app.tsx

import { ShopAssistProvider } from "@shopassist/react";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <ShopAssistProvider config={{ shopDomain: "your-shop.com" }}>
      <Component {...pageProps} />
    </ShopAssistProvider>
  );
}

Product URLs

The widget builds product links as /products/<handle>. If your routes differ, say so once and every link the assistant renders will match.

<ShopAssistProvider
  config={{
    shopDomain: "your-shop.com",
    custom: {
      currency: "EUR",
      language: "de",
      country: "DE",
      productUrlPattern: "/shop/{handle}",
      productPagePattern: "/shop/([^/?#]+)",
    },
  }}
>

See configuration for every field.

Content Security Policy

If your app sets a CSP, allow the widget's origins:

script-src 'self' https://widget.getshopassist.com;
connect-src 'self' https://api.getshopassist.com;

Next steps

Add to your cart from the chat.
Attribute orders back to conversations.