@evelan/jexity-widget

Embeddable AI chat widget for any website. Add customer support chat with a single <script> tag or via npm.

Quick Start

Script Tag (No Build Tools Required)

<script
  src="https://cdn.jexitychat.de/widget/latest/widget.js"
  data-org-slug="YOUR_ORG_SLUG"
  async
></script>

NPM

npm install @evelan/jexity-widget

import { JexityChat } from '@evelan/jexity-widget'

const chat = JexityChat({
  orgSlug: 'YOUR_ORG_SLUG',
})

// Later:
chat.shutdown()

React Provider

import { JexityChatProvider, useJexityChat } from '@evelan/jexity-widget/react'

function App() {
  return (
    <JexityChatProvider orgSlug="YOUR_ORG_SLUG">
      <HomePage />
    </JexityChatProvider>
  )
}

function HomePage() {
  const { open, close, toggle, isOpen } = useJexityChat()
  return <button onClick={open}>Chat with us</button>
}

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | orgSlug | string | required | Your organization slug (e.g. acme-corp) | | container | string \| HTMLElement | auto-created div | CSS selector or element to mount into | | position | 'bottom-right' \| 'bottom-left' | 'bottom-right' | Widget position on screen | | colorScheme | 'light' \| 'dark' \| 'auto' | 'auto' | Force color scheme; 'auto' follows system preference | | title | string | 'Jexity Assistant' | Chat window header title | | greeting | string | 'Hi! How can I help?' | Initial bot message shown on open | | primaryColor | string | '#0070f3' | Shorthand brand color — tints FAB, header, user bubbles, send button | | accentColor | string | — | Secondary accent color | | fontFamily | string | — | Override widget font family | | fontSize | number | — | Base font size in px | | borderRadius | string | — | Override widget corner radius (e.g. '8px') | | windowWidth | number | — | Chat window width in px | | windowHeight | number | — | Chat window height in px | | triggerIcon | 'chat' \| 'bot' \| 'sparkles' | 'chat' | Floating action button icon | | triggerRadius | 'none' \| 'sm' \| 'md' \| 'lg' \| 'full' | 'full' | FAB border radius shape | | triggerLabel | string | — | Text label shown next to the FAB | | hideBranding | boolean | false | Hide the "Powered by Jexity" footer | | locale | string | browser / 'de' | Force locale ('de' | 'en'). Overrides browser detection | | parentOrigin | string | window.location.origin | Trusted origin for postMessage dashboard preview updates | | theme | JexityTheme | — | Granular per-element color overrides (see below) |

Granular Theme Overrides

theme lets you override individual element colors. Unset keys fall back to primaryColor or brand defaults.

JexityChat({
  orgSlug: 'acme',
  theme: {
    bg: {
      trigger: '#1a1a2e',    // FAB background
      header: '#16213e',     // Chat header
      msgUser: '#0f3460',    // User bubble background
      msgBot: '#f5f5f5',     // Bot bubble background
      window: '#ffffff',     // Chat window background
      sendBtn: '#e94560',    // Send button background
    },
    text: {
      header: '#ffffff',     // Header text/icon color
      msgUser: '#ffffff',    // User bubble text
      msgBot: '#333333',     // Bot bubble text
      main: '#212121',       // Primary body text
      muted: '#888888',      // Secondary/muted text
    },
    border: {
      window: '#e0e0e0',     // Window border
      input: '#cccccc',      // Input field border
    },
  },
})

Programmatic API

const chat = JexityChat(options)

chat.open()                    // Open the chat window
chat.close()                   // Close the chat window
chat.toggle()                  // Toggle open/closed
chat.shutdown()                // Remove widget from DOM
chat.isOpen                    // readonly boolean — current open state
chat.subscribe(cb)             // Subscribe to open/close changes
                               // Returns unsubscribe function

// IIFE global (script tag):
window.JexityChat.open()
window.JexityChat.close()
window.JexityChat.toggle()
window.JexityChat.shutdown()

IIFE (Script Tag) Attributes

All options can be set as data-* attributes on the <script> tag:

<script
  src="https://cdn.jexitychat.de/widget/latest/widget.js"
  data-org-slug="acme-corp"
  data-locale="de"
  data-primary-color="#ff6600"
  data-trigger-icon="sparkles"
  data-trigger-radius="lg"
  data-trigger-label="Chat with us"
  data-hide-branding="true"
  data-convex-url="https://your-deployment.convex.cloud"
  async
></script>

Then control programmatically after load:

<script>
  window.JexityChat.open()
  window.JexityChat.shutdown()
</script>

Build Outputs

dist/
  widget.js          ← IIFE for <script> embed (CDN)
  index.mjs          ← ESM for bundlers (npm)
  react.mjs          ← React bindings (externalizes react + core)
  types/index.d.ts   ← TypeScript declarations (core)
  types/react.d.ts   ← TypeScript declarations (React)

Target sizes: IIFE ≤ 32 KB · ESM ≤ 42 KB (gzipped)

Development

# From repo root:
pnpm dev --filter @evelan/jexity-widget

# Or directly:
cd apps/widget
pnpm dev

Open http://localhost:3002 — the dev playground with live config controls.

Environment variables

Create apps/widget/.env.local:

# Convex deployment URL — used for both WebSocket (real-time) and HTTP actions (config fetch).
# The widget auto-derives .convex.site from .convex.cloud via convex-url.ts.
# Copy from packages/backend/.env.local (CONVEX_URL).
VITE_CONVEX_URL=https://<your-dev-deployment>.convex.cloud

# Reserved — not consumed yet. Future escape hatch if we ever swap Convex for
# a traditional REST backend (Express, Fastify, etc.). Once wired, widget code
# will read this instead of VITE_CONVEX_URL so the backend is hot-swappable
# via env alone.
# VITE_API_BASE_URL=https://api.example.com

URL Parameters

| Parameter | Example | Purpose | |-----------|---------|---------| | ?orgSlug= | ?orgSlug=demo | Set org slug (default: dev_local) | | ?primaryColor= | ?primaryColor=%230070f3 | Set primary color | | ?locale= | ?locale=en | Lock locale | | ?position= | ?position=bottom-left | Widget position | | ?title= | ?title=My+Assistant | Widget title | | ?hideBranding=true | — | Hide footer branding | | ?skipHomeScreen=true | — | Open directly to chat (skip landing) |

Build

pnpm build          # Full build (all 5 outputs)
pnpm check-types    # Type-check only (fast)

License

MIT