yoda-widget

A lightweight React + TypeScript chat widget that embeds a Yoda assistant on any page. It renders inside a Shadow DOM, supports theming, and talks to a FastAPI backend.

Install

npm install yoda-widget
# peer deps
npm install react react-dom

Quick start

import { useEffect } from 'react';
import { initYoda, setYodaEnabled, setYodaBackendUrl } from 'yoda-widget';

export default function App() {
  useEffect(() => {
    // Point to your backend once (default is http://localhost:8000)
    setYodaBackendUrl('http://localhost:8000');

    initYoda({
      authToken: 'YOUR_CLIENT_TOKEN',
      model: 'gemini',
      position: 'top-right',
      theme: {
        background: '#1a0909',
        headerBg: '#2a0d0d',
        text: '#ffe6e6',
        accent: '#7a1f1f',
        userBubble: '#5b1b1b',
        assistantBubble: '#3a1414',
        border: '#4a0e0e'
      }
    });
  }, []);
  return <div>Your app</div>;
}

API

initYoda(options)

Initializes the widget (idempotent).

initYoda({
  authToken: string;              // required client token
  model: 'gemini';                // required; reserved for future models
  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
  theme?: {
    background?: string;
    headerBg?: string;
    text?: string;
    accent?: string;
    userBubble?: string;
    assistantBubble?: string;
    border?: string;
  };
});

• The widget mounts to the page using a Shadow DOM host at a fixed corner.
• A default assistant greeting is shown on open.

setYodaEnabled(enabled)

Toggle the widget at runtime, useful for per-route control.

import { setYodaEnabled } from 'yoda-widget';

// Disable on a specific route
setYodaEnabled(false);

Example with React Router:

import { useLocation } from 'react-router-dom';
import { setYodaEnabled } from 'yoda-widget';

function RouterWatcher() {
  const location = useLocation();
  useEffect(() => {
    setYodaEnabled(location.pathname !== '/page');
  }, [location.pathname]);
  return null;
}

setYodaBackendUrl(url)

Set the backend base URL. Defaults to http://localhost:8000 if not set.

import { setYodaBackendUrl } from 'yoda-widget';
setYodaBackendUrl('https://api.example.com');

Backend expectations

The widget calls these endpoints on the configured backend (or same-origin):

• POST /v1/start_session -> { session_id }
• POST /v1/send_message -> { reply } (body includes session_id, message)
• POST /v1/end_session -> { success: true }
• Fallback single-turn: POST /v1/chat -> { reply }

Auth: All requests include Authorization: Bearer <authToken>.

CORS: If serving backend on a different origin, allow the frontend origin.

Theming

The widget uses CSS variables inside its Shadow DOM:

• --yoda-bg, --yoda-header-bg, --yoda-text, --yoda-accent,
• --yoda-user, --yoda-assistant, --yoda-border

You normally pass these via theme in initYoda. Advanced users can also override from the host with CSS variables if needed.

Notes

• React and ReactDOM are peer dependencies; the widget externalizes them.
• All styles are scoped to the Shadow DOM; no global CSS leak.
• The chat input auto-resizes; Shift+Enter inserts a newline, Enter sends.

License

MIT