TypeScript Chat Widget

This TypeScript chat widget provides a customizable, real-time chat interface that can be easily integrated into web applications. It uses WebSocket for real-time communication and supports various configuration options.

Features

• Real-time messaging using WebSocket
• Customizable appearance (position, theme)
• Automatic reconnection on connection loss
• TypeScript support with full type definitions
• JSDoc comments for better code documentation

Installation

1. Clone this repository or copy the TypeScript files into your project.
2. Install the required dependencies:

pnpm install

Builds

We publish two build targets so you can choose the flavour that best fits your stack:

| Build | File path inside the package | Format(s) | Typical consumer | |-----------|----------------------------------------------------|-----------|------------------| | React | dist/react/chat-widget.es.js (default export) | ES Module | React apps (Vite, Webpack, etc.) | | Vanilla | dist/vanilla/chat-widget.umd.js | UMD | Direct <script> tag, non-React frameworks |

Quick start

1. Install

pnpm add vowchat-chat-widget   # or npm / yarn

2. Use it

React (subpath import)

import VowChatWidget, { ChatWidget, type ChatWidgetInterface } from 'vowchat-chat-widget/react';

function App() {
  return (
    <VowChatWidget
      agent_id="your-agent-id"
      customer={{ id: '123', name: 'Jane Doe' }}
      position="bottom-right"
      theme="light"
    />
  );
}

Vanilla (CDN ESM)

<script type="module">
  import chatWidget from 'https://unpkg.com/vowchat-chat-widget/dist/vanilla/chat-widget.es.js';
  chatWidget({
    // mount: 'my-chat', // optional; auto-appends to body if omitted
    agent_id: 'your-agent-id',
    position: 'bottom-right',
    theme: 'light',
  });
  // jsDelivr alternative:
  // import chatWidget from 'https://cdn.jsdelivr.net/npm/vowchat-chat-widget/dist/vanilla/chat-widget.es.js';
</script>

Vanilla (bundlers)

import chatWidget, { type ChatWidgetInterface } from 'vowchat-chat-widget/vanilla';

chatWidget({
  mount: 'my-chat',
  agent_id: 'your-agent-id',
  position: 'bottom-right',
  theme: 'light',
});

Subpath imports summary

// React
import VowChatWidget, { ChatWidget, type ChatWidgetInterface } from 'vowchat-chat-widget/react';

// Vanilla (bundlers)
import chatWidget, { type ChatWidgetInterface } from 'vowchat-chat-widget/vanilla';

Tailwind CSS Integration

If your app uses Tailwind CSS, you may need to configure it to scan our widget's compiled files to ensure all Tailwind utility classes are included in your app's CSS bundle.

Why This May Be Needed

By default, Tailwind scans your app's source files but ignores node_modules. If our widget uses Tailwind classes that your app doesn't use, those classes might be missing from your final CSS, causing styling issues. This is a known issue with Tailwind component libraries.

Solution

Add our widget's compiled files to your Tailwind content configuration:

Tailwind CSS v3

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    // Add this line to scan our widget's compiled files
    './node_modules/vowchat-chat-widget/dist/**/*.{js,ts,jsx,tsx}',
  ],
  // ... rest of your config
}

Tailwind CSS v4

/* In your CSS file */
@import "tailwindcss";
@source "../node_modules/vowchat-chat-widget/dist";

References

• Tailwind CSS: Detecting classes in source files
• GitHub Discussion: Class collisions when installing tailwind component library

Configuration Options

• position: Position of the chat widget ("bottom-right", "bottom-left", "top-right", "top-left")
• theme: Color theme of the widget ("light" or "dark")
• companyName: Name of your company or support team
• orgID: Your organization's unique identifier
• fileID: (Optional) Unique identifier for aidentifier
• fileID: (Optional) Unique identifier for a specific file or conversation

Customization

You can customize the appearance of the chat widget by modifying your widget styles on your user dashboard

Shadow DOM embed (beta)

Status: This feature is in beta. API and file names may change.

What it is: A fully isolated Shadow DOM build that bundles React (UMD) so both React and non‑React apps can embed the widget without CSS clashes. Shadow CSS is injected inside the shadow root.

Exports:

vowchat-chat-widget/shadow              → dist/shadow/chat-widget.umd.js
vowchat-chat-widget/shadow/*            → everything under dist/shadow/* (e.g. style.css)

React usage (recommended)

Import the UMD and CSS as URLs and initialize:

import { useEffect, useRef } from 'react';
import umdUrl from 'vowchat-chat-widget/shadow/chat-widget.umd.js?url';
import cssUrl from 'vowchat-chat-widget/shadow/style.css?url';

declare global {
  interface Window {
    VowChatWidgetShadow?: {
      initShadowChatWidget: (opts: {
        mount?: string | HTMLElement;
        shadowRootMode?: 'open' | 'closed';
        cssHref?: string;
        agent_id: string;
        position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
        theme?: 'light' | 'dark';
      }) => void;
    };
  }
}

export function ShadowWidget() {
  const hostRef = useRef<HTMLDivElement | null>(null);

  useEffect(() => {
    let cancelled = false;
    (async () => {
      if (!window.VowChatWidgetShadow) {
        await new Promise<void>((resolve, reject) => {
          const s = document.createElement('script');
          s.src = umdUrl;
          s.async = true;
          s.onload = () => resolve();
          s.onerror = () => reject(new Error('Failed to load widget'));
          document.head.appendChild(s);
        });
      }
      if (cancelled || !hostRef.current || !window.VowChatWidgetShadow) return;
      window.VowChatWidgetShadow.initShadowChatWidget({
        mount: hostRef.current,
        cssHref: cssUrl,
        agent_id: 'YOUR_AGENT_ID',
        org_id: 'YOUR_ORG_ID',
        position: 'bottom-right',
        theme: 'light',
      });
    })();
    return () => { cancelled = true; };
  }, []);

  return <div ref={hostRef} />;
}

Notes:

• Do not also import the ESM build in the same page while testing UMD.
• If you include the UMD via a <script> tag in index.html, you may omit cssHref and rely on auto‑resolution of style.css next to the script.

Non‑React (plain HTML)

<script src="/path/to/chat-widget.umd.js"></script>
<script>
  window.VowChatWidgetShadow.initShadowChatWidget({
    cssHref: '/path/to/style.css',
    agent_id: 'YOUR_AGENT_ID',
    org_id: 'YOUR_ORG_ID',
    position: 'bottom-right',
    theme: 'light'
  });
  // Optionally pass mount: 'element-id' to use an existing host
</script>

Troubleshooting:

• If your bundler reports “Missing specifier” for shadow/*, ensure your version exports include "./shadow" and "./shadow/*".
• Clear Vite cache (node_modules/.vite) after updating the package and restart dev.