`html



`

Installer options:

- version - Package version to load (default: "latest")
- cdn - CDN provider: "jsdelivr" or "unpkg" (default: "jsdelivr")
- cssUrl - Custom CSS URL (overrides CDN)
- jsUrl - Custom JS URL (overrides CDN)
- target - CSS selector or element where widget mounts (default: "body")
- config - Widget configuration object (see Configuration reference)
- autoInit - Automatically initialize after loading (default: true)

Example with version pinning:

`html


`

#### Method 2: Manual installation

For more control, manually load CSS and JavaScript:

`html





`

CDN options:

- jsDelivr (recommended): https://cdn.jsdelivr.net/npm/vanilla-agent@VERSION/dist/
- unpkg: https://unpkg.com/vanilla-agent@VERSION/dist/

Replace VERSION with latest for auto-updates, or a specific version like 0.1.0 for stability.

Available files:

- widget.css - Stylesheet (required)
- index.global.js - Widget JavaScript (IIFE format)
- install.global.js - Automatic installer script

The script build exposes a window.AgentWidget global with initAgentWidget() and other exports, including parser functions:

- window.AgentWidget.initAgentWidget() - Initialize the widget
- window.AgentWidget.createPlainTextParser() - Plain text parser (default)
- window.AgentWidget.createJsonStreamParser() - JSON parser using schema-stream
- window.AgentWidget.createXmlParser() - XML parser
- window.AgentWidget.markdownPostprocessor() - Markdown postprocessor
- window.AgentWidget.directivePostprocessor() - Directive postprocessor (deprecated)
- window.AgentWidget.componentRegistry - Component registry for custom components

$3

The widget is fully compatible with React frameworks. Use the ESM imports to integrate it as a client component.

#### Framework Compatibility

| Framework | Compatible | Implementation Notes |
|-----------|------------|---------------------|
| Vite | ✅ Yes | No special requirements - works out of the box |
| Create React App | ✅ Yes | No special requirements - works out of the box |
| Next.js | ✅ Yes | Requires 'use client' directive (App Router) |
| Remix | ✅ Yes | Use dynamic import or useEffect guard for SSR |
| Gatsby | ✅ Yes | Use in wrapRootElement or check typeof window !== 'undefined' |
| Astro | ✅ Yes | Use client:load or client:only="react" directive |

#### Quick Start with Vite or Create React App

For client-side-only React frameworks (Vite, CRA), create a component:

`typescript
// src/components/ChatWidget.tsx
import { useEffect } from 'react';
import 'vanilla-agent/widget.css';
import { initAgentWidget, markdownPostprocessor } from 'vanilla-agent';
import type { AgentWidgetInitHandle } from 'vanilla-agent';

export function ChatWidget() {
useEffect(() => {
let handle: AgentWidgetInitHandle | null = null;

handle = initAgentWidget({
target: 'body',
config: {
apiUrl: "/api/chat/dispatch",
theme: {
primary: "#111827",
accent: "#1d4ed8",
},
launcher: {
enabled: true,
title: "Chat Assistant",
subtitle: "Here to help you get answers fast"
},
postprocessMessage: ({ text }) => markdownPostprocessor(text)
}
});

// Cleanup on unmount
return () => {
if (handle) {
handle.destroy();
}
};
}, []);

return null; // Widget injects itself into the DOM
}
`

Then use it in your app:

`typescript
// src/App.tsx
import { ChatWidget } from './components/ChatWidget';

function App() {
return (


export default App;
`

#### Next.js Integration

For Next.js App Router, add the 'use client' directive:

`typescript
// components/ChatWidget.tsx
'use client';

import { useEffect } from 'react';
import 'vanilla-agent/widget.css';
import { initAgentWidget, markdownPostprocessor } from 'vanilla-agent';
import type { AgentWidgetInitHandle } from 'vanilla-agent';

export function ChatWidget() {
useEffect(() => {
let handle: AgentWidgetInitHandle | null = null;

handle = initAgentWidget({
target: 'body',
config: {
apiUrl: "/api/chat/dispatch",
launcher: {
enabled: true,
title: "Chat Assistant",
},
postprocessMessage: ({ text }) => markdownPostprocessor(text)
}
});

return () => {
if (handle) {
handle.destroy();
}
};
}, []);

return null;
}
`

Use it in your layout or page:

`typescript
// app/layout.tsx
import { ChatWidget } from '@/components/ChatWidget';

export default function RootLayout({ children }) {
return (


{children}



);
}
`

Alternative: Dynamic Import (SSR-Safe)

If you encounter SSR issues, use Next.js dynamic imports:

`typescript
// app/layout.tsx
import dynamic from 'next/dynamic';

const ChatWidget = dynamic(
() => import('@/components/ChatWidget').then(mod => mod.ChatWidget),
{ ssr: false }
);

export default function RootLayout({ children }) {
return (


{children}



);
}
`

#### Remix Integration

For Remix, guard the widget initialization with a client-side check:

`typescript
// app/components/ChatWidget.tsx
import { useEffect, useState } from 'react';

export function ChatWidget() {
const [mounted, setMounted] = useState(false);

useEffect(() => {
setMounted(true);

// Dynamic import to avoid SSR issues
import('vanilla-agent/widget.css');
import('vanilla-agent').then(({ initAgentWidget, markdownPostprocessor }) => {
const handle = initAgentWidget({
target: 'body',
config: {
apiUrl: "/api/chat/dispatch",
launcher: { enabled: true },
postprocessMessage: ({ text }) => markdownPostprocessor(text)
}
});

return () => handle?.destroy();
});
}, []);

if (!mounted) return null;
return null;
}
`

#### Gatsby Integration

Use Gatsby's wrapRootElement API:

`typescript
// gatsby-browser.js
import { ChatWidget } from './src/components/ChatWidget';

export const wrapRootElement = ({ element }) => (
<>
{element}


);
`

#### Astro Integration

Use Astro's client directives with React islands:

`astro
---
// src/components/ChatWidget.astro
import { ChatWidget } from './ChatWidget.tsx';
---


`

#### Using the Theme Configurator

For easy configuration generation, use the Theme Configurator which includes a "React (Client Component)" export option. It generates a complete React component with your custom theme, launcher settings, and all configuration options.

#### Installation

`bash
npm install vanilla-agent


or

1. CSS Import: The CSS import (import 'vanilla-agent/widget.css') works natively with all modern React build tools
2. Client-Side Only: The widget manipulates the DOM, so it must run client-side only
3. Cleanup: Always call handle.destroy() in the cleanup function to prevent memory leaks
4. API Routes: Ensure your apiUrl points to a valid backend endpoint
5. TypeScript Support: Full TypeScript definitions are included for all exports

$3

The package exports a complete default configuration that you can use as a base:

`ts
import { DEFAULT_WIDGET_CONFIG, mergeWithDefaults } from 'vanilla-agent';

// Option 1: Use defaults with selective overrides
const controller = initAgentWidget({
target: '#app',
config: {
...DEFAULT_WIDGET_CONFIG,
apiUrl: '/api/chat/dispatch',
theme: {
...DEFAULT_WIDGET_CONFIG.theme,
accent: '#custom-color' // Override only what you need
}
}
});

// Option 2: Use the merge helper
const controller = initAgentWidget({
target: '#app',
config: mergeWithDefaults({
apiUrl: '/api/chat/dispatch',
theme: { accent: '#custom-color' }
})
});
`

This ensures all configuration values are set to sensible defaults while allowing you to customize only what you need.

$3

| Option | Type | Description |
| --- | --- | --- |
| apiUrl | string | Proxy endpoint for your chat backend (defaults to Travrse's cloud API). |
| flowId | string | Optional Travrse flow ID. If provided, the client sends it to the proxy which can use it to select a specific flow. |
| headers | Record | Extra headers forwarded to your proxy. |
| copy | { welcomeTitle?, welcomeSubtitle?, inputPlaceholder?, sendButtonLabel? } | Customize user-facing text. |
| theme | { primary?, secondary?, surface?, muted?, accent?, radiusSm?, radiusMd?, radiusLg?, radiusFull? } | Override CSS variables for the widget. Colors: primary (text/UI), secondary (unused), surface (backgrounds), muted (secondary text), accent (buttons/links). Border radius: radiusSm (0.75rem, inputs), radiusMd (1rem, cards), radiusLg (1.5rem, panels/bubbles), radiusFull (9999px, pills/buttons). |
| features | AgentWidgetFeatureFlags | Toggle UI features: showReasoning? (show thinking bubbles, default: true), showToolCalls? (show tool usage bubbles, default: true). |
| launcher | { enabled?, autoExpand?, title?, subtitle?, iconUrl?, position? } | Controls the floating launcher button. |
| initialMessages | AgentWidgetMessage[] | Seed the conversation transcript. |
| suggestionChips | string[] | Render quick reply buttons above the composer. |
| postprocessMessage | (ctx) => string | Transform message text before it renders (return HTML). Combine with markdownPostprocessor for rich output. |
| parserType | "plain" \| "json" \| "regex-json" \| "xml" | Built-in parser type selector. Easy way to choose a parser without importing functions. Options: "plain" (default), "json" (partial-json), "regex-json" (regex-based), "xml". If both parserType and streamParser are provided, streamParser takes precedence. |
| streamParser | () => AgentWidgetStreamParser | Custom stream parser for detecting formats and extracting text from streaming responses. Handles JSON, XML, or custom formats. See Stream Parser Configuration below. |
| clearChatHistoryStorageKey | string | Additional localStorage key to clear when the clear chat button is clicked. The widget automatically clears "vanilla-agent-chat-history" by default. Use this option to clear additional keys (e.g., if you're using a custom storage key). |
| formEndpoint | string | Endpoint used by built-in directives (defaults to /form). |
| launcherWidth | string | CSS width applied to the floating launcher panel (e.g. 320px, 90vw). Defaults to min(400px, calc(100vw - 24px)). |
| persistState | boolean \| AgentWidgetPersistStateConfig | Persist widget state (open/closed, voice mode) across page navigations. Set to true for defaults or pass an object for fine-grained control. See State Persistence below. |
| debug | boolean | Emits verbose logs to console. |

All options are safe to mutate via initAgentWidget(...).update(newConfig).

$3

The widget can parse structured responses (JSON, XML, etc.) that stream in chunk by chunk, extracting the text field for display. By default, it uses a plain text parser. You can easily select a built-in parser using parserType, or provide a custom parser via streamParser.

Key benefits of the unified stream parser:
- Format detection: Automatically detects if content matches your parser's format
- Extensible: Handle JSON, XML, or any custom structured format
- Incremental parsing: Extract text as it streams in, not just when complete

Quick start with parserType (recommended):

The easiest way to use a built-in parser is with the parserType option:

`javascript
import { initAgentWidget } from 'vanilla-agent';

const controller = initAgentWidget({
target: '#chat-root',
config: {
apiUrl: '/api/chat/dispatch',
parserType: 'json' // Options: 'plain', 'json', 'regex-json', 'xml'
}
});
`

Using built-in parsers with streamParser (ESM/Modules):

`javascript
import { initAgentWidget, createPlainTextParser, createJsonStreamParser, createXmlParser } from 'vanilla-agent';

const controller = initAgentWidget({
target: '#chat-root',
config: {
apiUrl: '/api/chat/dispatch',
streamParser: createJsonStreamParser // Use JSON parser
// Or: createXmlParser for XML, createPlainTextParser for plain text (default)
}
});
`

Using built-in parsers with CDN Script Tags:

`html


`

Using with automatic installer script:

`html


`

Alternative: Using streamParser with installer script:

If you need a custom parser, you can still use streamParser:

`html


`

Alternatively, you can set it after the script loads:

`html



`

Custom JSON parser example:

`javascript
const jsonParser = () => {
let extractedText = null;

return {
// Extract text field from JSON as it streams in
// Return null if not JSON or text not available yet
processChunk(accumulatedContent) {
const trimmed = accumulatedContent.trim();
// Return null if not JSON format
if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) {
return null;
}

const match = accumulatedContent.match(/"text"\s:\s"([^"](?:\\.[^"])*)"/);
if (match) {
extractedText = match[1].replace(/\\"/g, '"').replace(/\\n/g, '\n');
return extractedText;
}
return null;
},

getExtractedText() {
return extractedText;
}
};
};

initAgentWidget({
target: '#chat-root',
config: {
apiUrl: '/api/chat/dispatch',
streamParser: jsonParser,
postprocessMessage: ({ text, raw }) => {
// raw contains the structured payload (JSON, XML, etc.)
return markdownPostprocessor(text);
}
}
});
`

Custom XML parser example:

`javascript
const xmlParser = () => {
let extractedText = null;

return {
processChunk(accumulatedContent) {
// Return null if not XML format
if (!accumulatedContent.trim().startsWith('<')) {
return null;
}

// Extract text from ... tags
const match = accumulatedContent.match(/]>([\s\S]?)<\/text>/);
if (match) {
extractedText = match[1];
return extractedText;
}
return null;
},

getExtractedText() {
return extractedText;
}
};
};
`

Parser interface:

`typescript
interface AgentWidgetStreamParser {
// Process a chunk and return extracted text (if available)
// Return null if the content doesn't match this parser's format or text is not yet available
processChunk(accumulatedContent: string): Promise | string | null;

// Get the currently extracted text (may be partial)
getExtractedText(): string | null;

// Optional cleanup when parsing is complete
close?(): Promise | void;
}
`

The parser's processChunk method is called for each chunk. If the content matches your parser's format, return the extracted text and the raw payload. Built-in parsers already do this, so action handlers and middleware can read the original structured content without re-implementing a parser. Return null if the chunk isn't ready yet—the widget will keep waiting or fall back to plain text.

$3

The widget can automatically persist its state (open/closed, voice recognition mode) across page navigations using localStorage or sessionStorage. This is useful for multi-page websites where users navigate between pages.

Simple usage:

`typescript
initAgentWidget({
target: 'body',
config: {
apiUrl: '/api/chat/dispatch',
persistState: true // Enable with defaults
}
});
`

When enabled, the widget automatically:
- Re-opens if it was open before navigation
- Resumes voice recognition if it was active
- Focuses the text input if voice wasn't active
- Clears persisted state when chat is cleared

Advanced configuration:

`typescript
initAgentWidget({
target: 'body',
config: {
apiUrl: '/api/chat/dispatch',
persistState: {
enabled: true,
persist: {
openState: true, // Persist open/closed state (default: true)
voiceState: true, // Persist voice recognition state (default: true)
focusInput: true // Focus input after restore (default: true)
},
storage: 'localStorage', // or 'sessionStorage' (default: 'localStorage')
keyPrefix: 'vanilla-agent-', // Storage key prefix (default: 'vanilla-agent-')
clearOnChatClear: true // Clear state on chat clear (default: true)
}
}
});
`

With script tag installer:

`html


`

$3

The widget supports a preview mode that only loads when a specific URL query parameter is present. This is useful for testing, staging, or sharing preview links.

Programmatic usage:

`typescript
const widget = initAgentWidget({
target: 'body',
previewQueryParam: 'preview-agent', // Widget only loads with ?preview-agent=true
config: {
apiUrl: '/api/chat/dispatch'
}
});

// widget is null if preview param is missing
if (widget) {
console.log('Widget initialized!');
}
`

With script tag installer:

`html

`

Then visit your page with ?preview-agent=true to load the widget.

$3

The proxy server handles flow configuration and forwards requests to Travrse. You can configure it in three ways:

Option 1: Use default flow (recommended for getting started)

`ts
// api/chat.ts
import { createChatProxyApp } from 'vanilla-agent-proxy';

export default createChatProxyApp({
path: '/api/chat/dispatch',
allowedOrigins: ['https://www.example.com']
});
`

Option 2: Reference a Travrse flow ID

`ts
import { createChatProxyApp } from 'vanilla-agent-proxy';

export default createChatProxyApp({
path: '/api/chat/dispatch',
allowedOrigins: ['https://www.example.com'],
flowId: 'flow_abc123' // Flow created in Travrse dashboard or API
});
`

Option 3: Define a custom flow

`ts
import { createChatProxyApp } from 'vanilla-agent-proxy';

export default createChatProxyApp({
path: '/api/chat/dispatch',
allowedOrigins: ['https://www.example.com'],
flowConfig: {
name: "Custom Chat Flow",
description: "Specialized assistant flow",
steps: [
{
id: "custom_prompt",
name: "Custom Prompt",
type: "prompt",
enabled: true,
config: {
model: "meta/llama3.1-8b-instruct-free",
responseFormat: "markdown",
outputVariable: "prompt_result",
userPrompt: "{{user_message}}",
systemPrompt: "you are a helpful assistant, chatting with a user",
previousMessages: "{{messages}}"
}
}
]
}
});
`

Hosting on Vercel:

`ts
import { createVercelHandler } from 'vanilla-agent-proxy';

export default createVercelHandler({
allowedOrigins: ['https://www.example.com'],
flowId: 'flow_abc123' // Optional
});
`

Environment setup:

Add TRAVRSE_API_KEY to your environment. The proxy constructs the Travrse payload (including flow configuration) and streams the response back to the client.

$3

- The widget streams results using SSE and mirrors the backend flow_complete/step_chunk events.
- Tailwind-esc classes are prefixed with tvw- and scoped to #vanilla-agent-root, so they won't collide with the host page.
- Run pnpm dev from the repository root to boot the example proxy (examples/proxy) and the vanilla demo (examples/embedded-app).
- The proxy prefers port 43111` but automatically selects the next free port if needed.