@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>
}

Signed-in users: sign the pass on your server

@evelan/jexity-widget/server signs the pass for the user who is signed in, on your server only (Node 20+, Next.js route handlers, edge runtimes, Convex, Deno, Bun). No dependencies. The key decides the algorithm: a sign-in key from the Sign-in window signs HS256, a P-256 private key (JWK) whose public half is registered signs ES256.

// app/api/jexity-pass/route.ts (Next.js)
import { createJexityPass } from '@evelan/jexity-widget/server'

export async function GET() {
  const user = await getSignedInUser() // your app's own login, checked on the server
  if (!user) return new Response('', { status: 401 })
  const pass = await createJexityPass(
    { userId: user.id, name: user.name, email: user.emailVerified ? user.email : null, accountId: user.companyId },
    process.env.JEXITY_SIGN_IN_KEY,
  )
  return new Response(pass)
}

It keeps the pass inside what Jexity accepts: a long name is cut, an invalid email left out, iat/exp in seconds, 1 hour by default ({ lifetimeSeconds } up to 24 hours for a pass in the page). A user id over 128 characters throws instead of being cut, so two users never share a chat. A broken key throws a fixed message that never repeats the key.

Configuration

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.ask("How do I crawl?")    // Open the chat and send this question
chat.shutdown()                // Remove widget from DOM
chat.logout()                  // Signed-in user signed out: forget this tab's chats, start over with the current pass
chat.isOpen                    // readonly boolean — current open state
chat.subscribe(cb)             // Subscribe to open/close changes
                               // Returns unsubscribe function

// Your user signed out, also before the chat has loaded on this page:
import { logout } from "@evelan/jexity-widget" // or "@evelan/jexity-widget/react"
logout()                       // Forget this tab's chats

// 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)
  server.mjs/.cjs    ← createJexityPass for your server (no Preact, React or Convex)
  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

Build

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

License

MIT