Installing on React, Next.js & SPAs | Yokaify Docs

Next.js (App Router)

Add the script to your root layout with next/script:

// 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://cdn.yokaify.com/widget.js"
          data-site-key="YOUR_SITE_KEY"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

afterInteractive keeps the widget off the critical path — your page hydrates first, the mascot mounts right after.

Plain React (Vite, CRA)

Add the tag to index.html, before </body>:

<script src="https://cdn.yokaify.com/widget.js" data-site-key="YOUR_SITE_KEY" async></script>

Vue, Astro, SvelteKit & others

Same principle: put the script tag in the app shell / root layout that wraps every route. For Astro, place it in your base layout component; it works with both static and SSR output.

The widget patches history.pushState/replaceState and listens for popstate, so it knows when your app changes routes client-side. Behavior tracking and page-aware answers follow the visitor across routes without remounting. Two rules:

Load it once. Don't render the script inside a component that mounts per-route — that creates duplicate mascots.
Don't lazy-gate it behind a route. Put it in the shared layout so behavior signals start from the first page.

Identity & cart context (optional)

If your app knows who the visitor is, you can pass identity and cart data to the widget with data-yk-* attributes for verified order lookup and better assists. See the widget attributes reference.

Verify it worked

Run your app, navigate between routes, and confirm the mascot persists without remount flicker. The dashboard's Setup page detects the install automatically. Full checklist: Verify your installation.