{"id":48274150,"url":"https://github.com/thesysdev/genui-widget","last_synced_at":"2026-04-04T22:21:50.013Z","repository":{"id":321351704,"uuid":"1085497874","full_name":"thesysdev/genui-widget","owner":"thesysdev","description":"Embeddable Generative UI Chat widget","archived":false,"fork":false,"pushed_at":"2026-01-13T08:23:50.000Z","size":247,"stargazers_count":10,"open_issues_count":2,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T10:47:17.456Z","etag":null,"topics":["generative-ai","langchain","n8n"],"latest_commit_sha":null,"homepage":"https://www.thesys.dev/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thesysdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-29T05:52:15.000Z","updated_at":"2026-01-13T07:42:10.000Z","dependencies_parsed_at":"2025-10-29T07:32:52.857Z","dependency_job_id":null,"html_url":"https://github.com/thesysdev/genui-widget","commit_stats":null,"previous_names":["thesysdev/n8n-thesys-chat","thesysdev/chat-client","thesysdev/n8n-chat"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/thesysdev/genui-widget","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesysdev%2Fgenui-widget","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesysdev%2Fgenui-widget/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesysdev%2Fgenui-widget/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesysdev%2Fgenui-widget/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thesysdev","download_url":"https://codeload.github.com/thesysdev/genui-widget/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesysdev%2Fgenui-widget/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31416763,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T20:09:54.854Z","status":"ssl_error","status_checked_at":"2026-04-04T20:09:44.350Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["generative-ai","langchain","n8n"],"created_at":"2026-04-04T22:21:49.383Z","updated_at":"2026-04-04T22:21:49.998Z","avatar_url":"https://github.com/thesysdev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Generative UI Widget\n\nAn embeddable chat widget that lets your AI chatbots render rich, interactive UI like buttons, forms, charts, cards and more instead of plain text. Works out of the box with LangGraph/LangChain and n8n.\n\n[![Built with Thesys](https://thesys.dev/built-with-thesys-badge.svg)](https://thesys.dev)\n\n## Features\n\n- 🎨 **Beautiful UI** - Clean, modern chat interface\n- 🚀 **Easy Integration** - Single script tag or npm package\n- 💬 **Session Management** - Automatic session handling with persistent threads\n- 💾 **Flexible Storage** - localStorage, LangGraph-managed, or in-memory\n- 🗂️ **Thread Management** - Create, switch, and delete conversation threads\n- 🌓 **Theme Support** - Light and dark mode\n- 📱 **Responsive** - Works perfectly on mobile and desktop\n- 🔌 **Multi-Provider** - LangGraph, n8n, Make.com, or custom webhooks\n- 🌊 **Streaming Support** - Real-time streaming responses from your backend\n- 📐 **Multiple Layouts** - Full-page, side panel, or bottom tray form factors\n- 👋 **Welcome Message** - Customizable greeting when starting a new conversation\n- 💡 **Conversation Starters** - Pre-defined prompts to help users get started\n\n## Quick Start\n\n### Using LangGraph(/LangChain)\n\n```html\n\u003clink\n  href=\"https://cdn.jsdelivr.net/npm/genui-widget/dist/genui-widget.css\"\n  rel=\"stylesheet\"\n/\u003e\n\n\u003cscript type=\"module\"\u003e\n  import { createChat } from \"https://cdn.jsdelivr.net/npm/genui-widget/dist/genui-widget.es.js\";\n\n  createChat({\n    langgraph: {\n      deploymentUrl: \"https://your-deployment.langraph.app\",\n      assistantId: \"your-assistant-id\",\n    },\n    storageType: \"langgraph\", // Use LangGraph's built-in thread management\n    agentName: \"Assistant\",\n  });\n\u003c/script\u003e\n```\n\n### Using n8n or Custom Webhooks\n\n```html\n\u003clink\n  href=\"https://cdn.jsdelivr.net/npm/genui-widget/dist/genui-widget.css\"\n  rel=\"stylesheet\"\n/\u003e\n\n\u003cscript type=\"module\"\u003e\n  import { createChat } from \"https://cdn.jsdelivr.net/npm/genui-widget/dist/genui-widget.es.js\";\n\n  createChat({\n    n8n: {\n      webhookUrl: \"YOUR_WEBHOOK_URL\",\n      enableStreaming: true, // Optional: enable streaming responses\n    },\n    storageType: \"localstorage\", // Persist chats locally\n    agentName: \"Assistant\",\n  });\n\u003c/script\u003e\n```\n\n## Installation\n\n### CDN (Recommended)\n\nSee Quick Start above.\n\n### npm Package\n\n```bash\nnpm install genui-widget\n```\n\n```javascript\nimport { createChat } from \"genui-widget\";\n\n// With LangGraph\nconst chat = createChat({\n  langgraph: {\n    deploymentUrl: \"https://your-deployment.langraph.app\",\n    assistantId: \"your-assistant-id\",\n  },\n  storageType: \"langgraph\",\n});\n\n// OR with n8n/webhooks\nconst chat = createChat({\n  n8n: {\n    webhookUrl: \"YOUR_WEBHOOK_URL\",\n    enableStreaming: true,\n  },\n  storageType: \"localstorage\",\n});\n```\n\n## Configuration\n\n```javascript\nconst chat = createChat({\n  // Provider configuration (choose one)\n  langgraph: {\n    deploymentUrl: \"https://your-deployment.langraph.app\",\n    assistantId: \"your-assistant-id\",\n  },\n  // OR\n  n8n: {\n    webhookUrl: \"https://your-webhook-endpoint.com/chat\",\n    enableStreaming: true, // Optional: Enable streaming responses\n  },\n\n  // Optional settings\n  agentName: \"Assistant\", // Bot/agent name\n  logoUrl: \"https://example.com/logo.png\", // Logo image URL\n  theme: { mode: \"light\" }, // 'light' or 'dark'\n  storageType: \"langgraph\", // 'none', 'localstorage', or 'langgraph'\n  formFactor: \"full-page\", // 'full-page', 'side-panel', or 'bottom-tray'\n  enableDebugLogging: false, // Enable console debug logging\n\n  // Optional: Welcome message shown when thread is empty\n  welcomeMessage: {\n    title: \"Hi, I'm Assistant\",\n    description: \"I can help you with your questions.\",\n    image: { url: \"https://example.com/logo.png\" },\n  },\n\n  // Optional: Conversation starters\n  conversationStarters: {\n    variant: \"short\", // 'short' for pill buttons, 'long' for list items\n    options: [\n      { displayText: \"Help me get started\", prompt: \"Help me get started\" },\n      { displayText: \"What can you do?\", prompt: \"What can you do?\" },\n    ],\n  },\n\n  // Optional: Callbacks\n  onSessionStart: (sessionId) =\u003e {\n    console.log(\"Session started:\", sessionId);\n  },\n  onError: (error) =\u003e {\n    console.error(\"Chat error:\", error);\n  },\n});\n```\n\n### Storage Options\n\n**`storageType: \"none\"` (default):**\n\n- Messages work normally during the session\n- All data is lost on page refresh\n- Best for: Simple use cases, demos, or privacy-focused applications\n\n**`storageType: \"localstorage\"`:**\n\n- Chat conversations persist across page refreshes\n- Users can create and manage multiple threads\n- Thread history is saved to browser localStorage\n- Best for: n8n/webhook integrations without built-in persistence\n\n**`storageType: \"langgraph\"`:**\n\n- Leverages LangGraph's built-in thread management\n- Conversations persist server-side across devices\n- Requires `langgraph` provider configuration\n- Thread operations (create, delete, update) sync with LangGraph API\n- Best for: LangGraph deployments requiring cross-device sync\n\n### Programmatic Control\n\n```javascript\n// Get current session ID\nconst sessionId = chat.getSessionId();\n\n// Open the chat window\nchat.open();\n\n// Close the chat window\nchat.close();\n\n// Destroy the widget completely\nchat.destroy();\n```\n\n## Provider Integration\n\n### LangGraph\n\nThe widget integrates seamlessly with [LangGraph](https://langchain-ai.github.io/langgraph/) deployments (Cloud or self-hosted).\n\n**Configuration:**\n\n```javascript\ncreateChat({\n  langgraph: {\n    deploymentUrl: \"https://your-deployment.langraph.app\",\n    assistantId: \"your-assistant-id\",\n  },\n  storageType: \"langgraph\", // Recommended for LangGraph\n});\n```\n\n**Features:**\n\n- ✅ **Automatic Thread Management** - Creates and manages threads via LangGraph API\n- ✅ **Server-Side Persistence** - Conversations persist across devices\n- ✅ **Streaming Support** - Real-time streaming via Server-Sent Events (SSE)\n- ✅ **Message History** - Fetches and displays conversation history\n- ✅ **Thread Operations** - Create, update, delete threads with metadata\n\n**How it works:**\n\n1. Widget calls `POST /threads` to create new conversation threads\n2. Messages sent via `POST /threads/{thread_id}/runs/stream` with streaming enabled\n3. Thread history retrieved via `GET /threads/{thread_id}/history`\n4. Thread list fetched via `POST /threads/search`\n\nThe LangGraph provider automatically handles the streaming response format and extracts message content from the SSE events.\n\n## Webhook Integration\n\n### Request Format\n\nThe chat client sends POST requests to your webhook:\n\n```json\n{\n  \"chatInput\": \"User's message here\",\n  \"sessionId\": \"uuid-v4-session-id\"\n}\n```\n\n### Response Format\n\n**Non-streaming mode:**\n\n```json\n{\n  \"output\": \"Your bot's response here\"\n}\n```\n\n**Streaming mode (`enableStreaming: true`):**\n\nReturn line-delimited JSON chunks:\n\n```\n{ \"type\": \"item\", \"content\": \"First chunk \" }\n{ \"type\": \"item\", \"content\": \"second chunk \" }\n{ \"type\": \"item\", \"content\": \"final chunk\" }\n```\n\n## Provider Setup\n\n### n8n\n\nFollow the instructions at [thesys.dev/n8n](https://thesys.dev/n8n) to quickly set up your n8n workflow.\n\n## Configuration Reference\n\nComplete list of all available options:\n\n### Provider Configuration\n\n**You must configure either `langgraph` OR `n8n` (not both):**\n\n#### langgraph (optional)\n\n```typescript\nlanggraph?: {\n  // Required: Your LangGraph deployment URL\n  deploymentUrl: string;\n\n  // Required: The assistant ID to use\n  assistantId: string;\n}\n```\n\nUse this for LangGraph Cloud or self-hosted deployments. When using LangGraph, set `storageType: \"langgraph\"` to leverage server-side thread management.\n\n#### n8n (optional)\n\n```typescript\nn8n?: {\n  // Required: Your webhook URL\n  webhookUrl: string;\n\n  // Optional: Enable streaming responses (default: false)\n  enableStreaming?: boolean;\n\n  // Optional: Custom webhook configuration\n  webhookConfig?: {\n    method?: string;                    // HTTP method (default: \"POST\")\n    headers?: Record\u003cstring, string\u003e;   // Custom headers\n  };\n}\n```\n\nUse this for n8n, Make.com, or any custom webhook endpoint.\n\n### agentName (optional)\n\n```typescript\nagentName?: string;  // Default: \"Assistant\"\n```\n\nThe name displayed for the bot/agent in the chat interface.\n\n### logoUrl (optional)\n\n```typescript\nlogoUrl?: string;\n```\n\nURL to a logo image that will be displayed in the chat interface.\n\n### enableDebugLogging (optional)\n\n```typescript\nenableDebugLogging?: boolean;  // Default: false\n```\n\nEnable debug logging to the browser console. Useful for troubleshooting webhook integration issues.\n\n### theme (optional)\n\n```typescript\ntheme?: {\n  mode: 'light' | 'dark';  // Default: 'light'\n}\n```\n\nSets the color scheme for the chat interface.\n\n### storageType (optional)\n\n```typescript\nstorageType?: 'none' | 'localstorage' | 'langgraph';  // Default: 'none'\n```\n\nControls chat history persistence:\n\n- `'none'` - Messages are kept in memory only, lost on page refresh\n- `'localstorage'` - Messages are saved to browser localStorage, persist across sessions\n- `'langgraph'` - Uses LangGraph's server-side thread management (requires `langgraph` provider)\n\n### welcomeMessage (optional)\n\n```typescript\nwelcomeMessage?: {\n  title?: string;       // Main heading text\n  description?: string; // Subheading/description text\n  image?: { url: string }; // Optional logo/image\n} | React.ComponentType; // Or provide a custom component\n```\n\nDisplayed when the thread is empty to greet users.\n\n**Example:**\n\n```javascript\ncreateChat({\n  n8n: { webhookUrl: \"YOUR_WEBHOOK_URL\" },\n  welcomeMessage: {\n    title: \"Hi, I'm Assistant\",\n    description: \"I can help you with your questions.\",\n    image: { url: \"/logo.png\" },\n  },\n});\n```\n\n### conversationStarters (optional)\n\n```typescript\nconversationStarters?: {\n  variant?: 'short' | 'long'; // 'short' = pill buttons, 'long' = list items\n  options: Array\u003c{\n    displayText: string; // Text shown on the button\n    prompt: string;      // Message sent when clicked\n    icon?: React.ReactNode; // Optional icon\n  }\u003e;\n}\n```\n\nClickable prompts shown when the thread is empty to help users begin a conversation.\n\n**Example:**\n\n```javascript\ncreateChat({\n  n8n: { webhookUrl: \"YOUR_WEBHOOK_URL\" },\n  conversationStarters: {\n    variant: \"short\",\n    options: [\n      { displayText: \"Help me get started\", prompt: \"Help me get started\" },\n      { displayText: \"What can you do?\", prompt: \"What can you do?\" },\n      { displayText: \"Show me examples\", prompt: \"Show me some examples\" },\n    ],\n  },\n});\n```\n\n### formFactor (optional)\n\n```typescript\nformFactor?: 'full-page' | 'side-panel' | 'bottom-tray';  // Default: 'full-page'\n```\n\nControls the layout form factor:\n\n- `'full-page'` - Takes up the entire viewport\n- `'side-panel'` - Displays as a side panel on the right\n- `'bottom-tray'` - Appears as a collapsible tray at the bottom of the screen\n\n\u003e **Note:** The `mode` property is deprecated. Use `formFactor` instead (`'fullscreen'` → `'full-page'`, `'sidepanel'` → `'side-panel'`).\n\n### bottomTray (optional)\n\n```typescript\nbottomTray?: {\n  // Control the open state of the bottom tray (controlled mode)\n  isOpen?: boolean;\n\n  // Callback when bottom tray open state changes\n  onOpenChange?: (isOpen: boolean) =\u003e void;\n\n  // Default open state for bottom tray (uncontrolled mode)\n  defaultOpen?: boolean;\n}\n```\n\nConfiguration options specific to the `bottom-tray` form factor. Only used when `formFactor` is set to `'bottom-tray'`.\n\n**Example usage:**\n\n```javascript\ncreateChat({\n  n8n: { webhookUrl: \"YOUR_WEBHOOK_URL\" },\n  formFactor: \"bottom-tray\",\n  bottomTray: {\n    defaultOpen: false, // Start collapsed\n    onOpenChange: (isOpen) =\u003e {\n      console.log(\"Tray is now:\", isOpen ? \"open\" : \"closed\");\n    },\n  },\n});\n```\n\n**Controlled vs Uncontrolled mode:**\n\n- **Uncontrolled:** Use `defaultOpen` to set initial state, let the widget manage it\n- **Controlled:** Use `isOpen` and `onOpenChange` to fully control the tray state externally\n\n### onSessionStart (optional)\n\n```typescript\nonSessionStart?: (sessionId: string) =\u003e void;\n```\n\nCallback function that fires when a new chat session is created. Receives the session ID as a parameter. Useful for analytics or tracking.\n\n### onError (optional)\n\n```typescript\nonError?: (error: Error) =\u003e void;\n```\n\nCallback function that fires when an error occurs during message processing. Useful for logging, analytics, or custom error handling. Note that the widget will still display error states in the chat UI automatically.\n\n## Troubleshooting\n\n### Chat doesn't load\n\n- Check browser console for errors (enable `enableDebugLogging: true`)\n- Verify provider configuration is correct (LangGraph URL/assistant ID or webhook URL)\n- Ensure endpoint is active and accessible\n- Check CORS settings\n\n### Connection errors\n\n**For LangGraph:**\n\n- Verify `deploymentUrl` and `assistantId` are correct\n- Check that the LangGraph deployment is running\n- Ensure your assistant is deployed and accessible\n\n**For n8n/webhooks:**\n\n- Verify webhook URL is correct\n- Check CORS configuration\n- Ensure your domain is allowlisted (for n8n)\n- Test webhook endpoint independently\n\n### Messages not sending or displaying\n\n**For LangGraph:**\n\n- Check that streaming is working (SSE connection)\n- Verify assistant is responding correctly\n- Check thread creation/access permissions\n\n**For n8n/webhooks:**\n\n- Verify response format: `{ \"output\": \"message\" }`\n- For streaming, ensure line-delimited JSON format\n- Check webhook execution logs\n- Enable `enableStreaming` if using streaming responses\n\n### Storage issues\n\n- If using `storageType: \"langgraph\"`, ensure LangGraph provider is configured\n- For localStorage, check browser storage isn't full\n- Clear localStorage if you encounter corrupted state: `localStorage.clear()`\n\n## Requirements\n\n- **Node.js**: Version 20.9.0 or higher (for development)\n\n## Browser Support\n\n- Chrome/Edge (latest 2 versions)\n- Firefox (latest 2 versions)\n- Safari (latest 2 versions)\n- Mobile browsers (iOS Safari, Chrome Mobile)\n\n## License\n\nMIT\n\n## Support\n\n- GitHub Issues: [Create an issue](https://github.com/thesysdev/genui-widget/issues)\n- Documentation: [View docs](https://github.com/thesysdev/genui-widget)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthesysdev%2Fgenui-widget","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthesysdev%2Fgenui-widget","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthesysdev%2Fgenui-widget/lists"}