@startstorez/support-chat

Embeddable AI support chat widget for React apps. Drop in one component and your users get streaming, grounded answers from your documentation — with source citations and a "talk to a human" escalation.

• 🟣 One component — <SupportChat appKey="…" apiBaseUrl="…" />
• ⚡ Streaming answers (SSE), markdown, typing indicator
• 📚 Citations — links back to the source docs
• 🧠 Memory — conversation persists across reloads
• 🎨 Per-store theming — light / dark / auto + accent color
• 🧩 Self-contained — no CSS import, styles are scoped (ssc-), host layout untouched
• ♿ Accessible — keyboard, focus trap, ARIA, reduced-motion
• 🛍️ Works in Shopify embedded apps, React, and Next.js

Install

npm install @startstorez/support-chat
# or: pnpm add @startstorez/support-chat   /   yarn add @startstorez/support-chat

react and react-dom (>=18) are peer dependencies.

Quick start

import { SupportChat } from '@startstorez/support-chat';

export function App() {
  return (
    <>
      {/* your app */}
      <SupportChat
        appKey="app_xxxxxxxx"                  // REQUIRED — scopes answers to your app's docs
        apiBaseUrl="https://api.yoursite.com/api/v1"
        docsBaseUrl="https://docs.yoursite.com"
        appSlug="your-app"
        theme="auto"
        accentColor="#4f46e5"
        title="Support"
        suggestedQuestions={[
          'How do I install the app?',
          'Why is X not working?',
        ]}
        supportEmail="[email protected]"
      />
    </>
  );
}

A floating launcher appears in the bottom-right. Clicking it opens a chat window overlay — your app's layout is never affected.

appKey is required. It identifies which app's knowledge base to answer from (multi-tenant). Wrong/missing key = the widget won't work.

Usage by platform

React (Vite / CRA / etc.)

Just render <SupportChat /> anywhere near the root (see Quick start above).

Next.js (App Router)

The widget uses window / localStorage, so render it in a client component:

// components/support-widget.tsx
'use client';
import { SupportChat } from '@startstorez/support-chat';

export function SupportWidget() {
  return (
    <SupportChat
      appKey="app_xxxxxxxx"
      apiBaseUrl={process.env.NEXT_PUBLIC_API_BASE_URL!}
    />
  );
}

// app/layout.tsx (or any layout)
import { SupportWidget } from '@/components/support-widget';

export default function Layout({ children }) {
  return (
    <>
      {children}
      <SupportWidget />
    </>
  );
}

Use a NEXT_PUBLIC_ env var for apiBaseUrl — the widget calls the API from the browser.

Shopify embedded admin app (React + Polaris + App Bridge)

A Shopify embedded app is a normal React app, so it works the same way. Render it inside your app frame:

import { SupportChat } from '@startstorez/support-chat';

export function AppFrame({ children }) {
  return (
    <>
      {children}
      <SupportChat
        appKey="app_xxxxxxxx"
        apiBaseUrl="https://api.yoursite.com/api/v1"
        theme="auto"            // matches the merchant's admin (light/dark)
      />
    </>
  );
}

• Styles are scoped (ssc- prefix) so they won't clash with Polaris.
• The window is a fixed overlay — it won't affect your app's layout or the Shopify admin frame.

Not for storefronts. This widget is for merchant-facing surfaces (embedded admin app / dashboards), not the Liquid storefront.

Backend / CORS

The widget calls POST {apiBaseUrl}/public/chat (SSE) and GET {apiBaseUrl}/public/chat/:id from the browser, using the appKey as the x-app-key header. Make sure your API allows the host app's origin (CORS) for the /public/* routes.

Props

| Prop | Required | Description | |---|---|---| | appKey | ✅ | App public key — scopes the knowledge base to this app | | apiBaseUrl | ✅ | Backend base, e.g. https://api.yoursite.com/api/v1 | | docsBaseUrl | – | Build citation links when the API omits a full url | | appSlug | – | App slug, used with docsBaseUrl for citation links | | theme | – | light | dark | auto (default auto) | | accentColor | – | Brand accent (launcher, buttons, links) | | position | – | bottom-right (default) | bottom-left | | defaultOpen | – | Open the window on mount | | title | – | Window header text | | greeting | – | Empty-state greeting | | placeholder | – | Composer placeholder | | suggestedQuestions | – | Starter prompts shown on first open | | supportEmail | – | Escalation CTA target (mailto) | | user, shop | – | Context passed to the backend (analytics / escalation) | | onEscalate | – | Callback fired when the bot escalates |

Behaviour

• Floating launcher → window overlay (host layout untouched). Close returns to the launcher.
• Streaming answers render as markdown (sanitized). A typing indicator shows while generating.
• Citations list the source docs; click to open them.
• Escalation: when the bot can't help (or the user asks for a human), an escalation card appears.
• Memory: the conversation id is stored in localStorage (per appKey); reopening or refreshing restores the conversation. "New chat" clears it.
• Theming is driven by CSS variables — fully scoped, no global CSS leakage.

License

MIT