@erica/bubble

Erica AI Chat Widget - A self-contained React component for integrating Erica AI assistant into your application

Features

• ✅ Plug-and-Play - Zero configuration required
• ✅ Self-Contained - All dependencies bundled (except peer deps)
• ✅ Type-Safe - Full TypeScript support
• ✅ Thread Management - Built-in conversation history
• ✅ File Upload - Drag & drop file attachments
• ✅ Responsive - Works on desktop and mobile
• ✅ Customizable - Flexible styling options

Installation

npm install @erica/bubble @copilotkit/react-core @copilotkit/react-ui

or with yarn:

yarn add @erica/bubble @copilotkit/react-core @copilotkit/react-ui

Quick Start

import { EricaChat } from '@erica/bubble';
import '@erica/bubble/styles.css';

function App() {
  return (
    <div style={{ height: '100vh' }}>
      <EricaChat
        runtimeUrl="https://api.example.com/widget/account-123"
        widgetToken="your-widget-token"
      />
    </div>
  );
}

That's it! No additional setup required.

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | runtimeUrl | string | ✅ | Widget runtime endpoint URL (includes account UID) | | widgetToken | string | ✅ | JWT token from widget authentication |

Authentication Flow

1. Get Widget Token

First, authenticate with the widget login endpoint:

const response = await fetch('https://api.example.com/widget/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'password',
    accountUid: 'your-account-uid',
  }),
});

const { widgetToken, accountUid } = await response.json();

2. Use Widget Token

Pass the token to the EricaChat component:

<EricaChat
  runtimeUrl={`https://api.example.com/widget/${accountUid}`}
  widgetToken={widgetToken}
/>

Complete Example

import { useState, useEffect } from 'react';
import { EricaChat } from '@erica/bubble';
import '@erica/bubble/styles.css';

function App() {
  const [auth, setAuth] = useState(null);

  const handleLogin = async (email, password, accountUid) => {
    const response = await fetch('https://api.example.com/widget/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password, accountUid }),
    });

    const data = await response.json();
    setAuth(data);
  };

  if (!auth) {
    return <LoginForm onLogin={handleLogin} />;
  }

  return (
    <div style={{ height: '100vh' }}>
      <EricaChat
        runtimeUrl={`https://api.example.com/widget/${auth.accountUid}`}
        widgetToken={auth.widgetToken}
      />
    </div>
  );
}

Features

Thread History

The component automatically fetches and displays conversation history. Users can:

• View recent threads in the dropdown
• Switch between conversations
• Start new chats

File Upload

Built-in file upload support:

• Drag & drop files
• Click to browse
• Upload progress indicator
• File preview chips

Responsive Design

Optimized for all screen sizes:

• Desktop: Full sidebar experience
• Mobile: Collapsible chat interface
• Tablet: Adaptive layout

Styling

Default Styles

Import the default stylesheet:

import '@erica/bubble/styles.css';

Custom Styling

The component uses standard CSS classes that you can override:

/* Customize chat container */
.copilot-sidebar {
  /* your styles */
}

/* Customize input area */
.copilot-input {
  /* your styles */
}

TypeScript

Full TypeScript support with exported types:

import { EricaChat, type EricaChatProps } from '@erica/bubble';

const props: EricaChatProps = {
  runtimeUrl: 'https://api.example.com/widget/account-123',
  widgetToken: 'token',
};

<EricaChat {...props} />

Peer Dependencies

This package requires the following peer dependencies:

• react ^18.0.0 || ^19.0.0
• react-dom ^18.0.0 || ^19.0.0
• @copilotkit/react-core ^1.55.0
• @copilotkit/react-ui ^1.55.0

These are not bundled to avoid version conflicts and reduce bundle size.

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

Bundle Size

• Minified: ~150 KB
• Gzipped: ~45 KB

Includes:

• React Query for state management
• Lucide React for icons
• All widget functionality

API Requirements

Your backend must provide these endpoints:

Login Endpoint

POST /api/widget/login

Runtime Endpoint

POST /api/widget/{accountUid}

Thread Endpoints

GET /api/widget/threads
GET /api/widget/threads/{threadUid}

Attachment Endpoints

POST /api/widget/attachments/upload
GET /api/widget/attachments/{filename}

See Backend Integration Guide for details.

Troubleshooting

Component not rendering

Ensure peer dependencies are installed:

npm install @copilotkit/react-core @copilotkit/react-ui

Styles not applied

Import the stylesheet:

import '@erica/bubble/styles.css';

401 Unauthorized errors

Check that:

• Widget token is valid and not expired
• Runtime URL includes correct account UID
• Backend endpoints are accessible

CORS errors

Ensure your backend has proper CORS headers:

'Access-Control-Allow-Origin': '*'
'Access-Control-Allow-Methods': 'GET, POST, OPTIONS'
'Access-Control-Allow-Headers': 'Content-Type, Authorization'

Examples

See the examples directory for complete working examples:

• Basic Integration
• With Authentication
• Custom Styling
• Next.js Integration

Development

# Clone repository
git clone https://github.com/your-org/erica-bubble.git

# Install dependencies
npm install

# Run development server
npm run dev

# Build library
npm run build:lib

# Run tests
npm test

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT © [Your Organization]

Support

• 📧 Email: [email protected]
• 💬 Discord: Join our server
• 📖 Documentation: docs.example.com
• 🐛 Issues: GitHub Issues

Changelog

See CHANGELOG.md for release history.