A standalone chatbox widget for Fleek agents
A standalone widget that allows users to embed a chatbox on any website to interact with a Fleek agent. This lightweight, customizable widget can be easily integrated into any website with a simple script tag or imported as a React component.
The Fleek Chatbox Widget is a drop-in solution for adding AI chat capabilities to your website. It provides:
- A floating chat button that expands into a full chat interface
- Real-time messaging with Fleek AI agents
- Customizable appearance through CSS variables
- Responsive design that works on both desktop and mobile devices
- Lightweight implementation using Preact
- Available as both a standalone script and a React component
To set up the project for development:
``bash
git clone https://github.com/fleek-platform/chatbox-widget.git
cd chatbox-widget
npm install
`
`bash`
npm install @fleek-platform/agents-chatbox-widget
To start the development server:
`bash`
npm run dev
This will:
1. Build the project using Rollup with watch mode
2. Start a live server that opens test/index.html
3. Automatically reload when changes are detected
`
fleek-chatbox-widget/
├── dist/ # Built files (generated)
├── src/ # Source code
│ ├── components/ # UI components
│ │ ├── icons/ # SVG icons as React components
│ │ └── *.tsx # Component files
│ ├── core/ # Core functionality
│ │ ├── api.ts # API client
│ │ ├── types.ts # TypeScript type definitions
│ │ └── utils.ts # Utility functions
│ ├── npm/ # React/NPM package entry point
│ │ └── index.ts # NPM package entry
│ ├── standalone/ # Standalone script
│ │ └── chatbox.ts # Standalone entry point
│ └── global.css # Global styles and CSS variables
├── examples/ # Example usage
│ ├── react-app/ # React example
├── test/ # Test files
│ └── index.html # Test page for development
├── package.json # Project dependencies and scripts
└── rollup.config.js # Rollup build configuration
To build the project for production:
`bash
npm run build
npm run build:standalone
npm run build:npm
`
This creates the following files in the dist/ directory:
- dist/chatbox.min.js - The standalone script to be included on websitesdist/index.esm.js
- - ES module for npm packagedist/index.cjs.js
- - CommonJS module for npm packagedist/index.d.ts
- - TypeScript declarations
This project uses Changesets for versioning and automated releases.
1. Make your changes to the codebase
2. Add a changeset to describe your changes:
`bash`
npx changeset
3. Follow the prompts to select the type of change (major, minor, patch) and provide a description
4. Commit the generated changeset file along with your code changes
5. Create a pull request
6. When the PR is merged to main, a GitHub Action will:
- Create a version PR if there are changesets
- When the version PR is merged:
- Update the version in package.json
- Update the CHANGELOG.md
- Publish to npm
- Deploy the standalone script to GitHub Pages
For production use, we recommend using a specific version of the standalone script:
`html`
async
>
> [!NOTE]
> Replace , and with your own details.
To add the Fleek Chatbox Widget to your website using the standalone script, include the script tag in your HTML:
`html`
async
>
> [!NOTE]
> Replace , , and with your own details.
#### Parameters
- agentId (required): Your Fleek agent IDtoken
- (required): Your TOKEN for authenticationrestApiHost
- (optional): Custom API host URL (defaults to production URL if not provided)containerId
- (optional): ID of an existing element to render the widget into
Example:
`html`
async
>
> [!WARNING]
> You must replace the values in the script src with your own details.
When using the containerId parameter, you need to have an element with that ID in your HTML:
`html`
To use the Fleek Chatbox Widget in a React application:
`jsx
import React from 'react';
import FleekChatbox from '@fleek-platform/agents-chatbox-widget';
function App() {
return (
export default App;
`
#### Props
- agentId (required): Your Fleek agent IDtoken
- (required): Your token for authenticationcolors
- (optional): An object with color overridesrestApiHost
- (optional): Custom API host URL (defaults to production URL if not provided)isWidgetOpen
- (optional): Boolean to control if the widget is initially open (default: false)
Example:
`jsx`
token="abc123"
restApiHost="https://api.custom-domain.com"
colors={{
'accent-9': '#ff0000',
'neutral-3': '#f5f5f5',
}}
isWidgetOpen={true}
/>
You can specify a custom API host for the widget to connect to by using the restApiHost parameter:
`html`
async
>
If no restApiHost is specified, the widget will connect to the production API at https://api.fleek.xyz.
This is useful when you need to connect to a custom API endpoint or a self-hosted version of the Fleek API.
You can customize the appearance of the widget by overriding the default colors. This is done by passing a JSON object in the colors parameter:
`html`
async
>
> [!NOTE]
> Replace , and with your own details.
The colors parameter is a URL-encoded JSON object where:
- Keys are CSS variable names without the -- prefix
- Values are valid CSS color values
Example (before URL encoding):
`json`
{
"accent-9": "#ff0000",
"neutral-3": "#f5f5f5"
}
When using the React component, you can pass the colors directly as an object:
`jsx`
token="abc123"
colors={{
'accent-9': '#ff0000',
'neutral-3': '#f5f5f5',
}}
/>
- Neutral colors: --neutral-1 through --neutral-12
- Accent colors: through --accent-12
- Warning colors: through --warning-12
These color variables can be used to customize the appearance of the widget to match your website's design.
#### Widget doesn't appear on the page
- Check that the script URL is correct
- Verify that your agentId and token are valid
- Check the browser console for any JavaScript errors
- Ensure there are no Content Security Policy (CSP) restrictions blocking the script
#### Custom colors not applying
- Make sure your JSON is properly URL-encoded (for standalone script)
- Check the browser console for any parsing errors
- Verify the color variable names match those in the documentation
#### Widget appears but agent doesn't respond
- Verify your API key has the correct permissions
- Check that the agent ID is correct and the agent is active
- Look for network errors in the browser's developer tools
The widget outputs information to the browser console that can help with troubleshooting. Check your browser's developer tools console for messages related to the widget's initialization and operation.
- Follow the existing code style
- Write clear, descriptive commit messages
- Always include a changeset for changes that affect functionality
- Add tests for new features
- Update documentation as needed
This project uses Biome for formatting and linting:
`bash
npm run format
npm run format:check
npm run lint
npm run lint:check
`
This section guides you through the process of contributing to our open-source project. From creating a feature branch to submitting a pull request, get started by:
1. Fork the project here
2. Create your feature branch using our branching strategy, e.g. git checkout -b feat/my-new-feature
3. Run the tests:
4. Commit your changes by following our commit conventions, e.g.
5. Push to the branch, e.g.
6. Create new Pull Request following the corresponding template guidelines
The develop branch serves as the main integration branch for features, enhancements, and fixes. It is always in a deployable state and represents the latest development version of the application.
Feature branches are created from the develop branch and are used to develop new features or enhancements. They should be named according to the type of work being done and the scope of the feature and in accordance with conventional commits here.
We prefer to commit our work following Conventional Commits conventions. Conventional Commits are a simple way to write commit messages that both people and computers can understand. It help us keep track fo changes in a consistent manner, making it easier to see what was added, changed, or fixed in each commit or update.
The commit messages are formatted as [type]/[scope]
The type is a short descriptor indicating the nature of the work (e.g., feat, fix, docs, style, refactor, test, chore). This follows the conventional commit types.
The scope is a more detailed description of the feature or fix. This could be the component or part of the codebase affected by the change.
Here's an example of different conventional commits messages that you should follow:
`txt``
test: 💍 Adding missing tests
feat: 🎸 A new feature
fix: 🐛 A bug fix
chore: 🤖 Build process or auxiliary tool changes
docs: 📝 Documentation only changes
refactor: 💡 A code change that neither fixes a bug or adds a feature
style: 💄 Markup, white-space, formatting, missing semi-colons...