nextjs-chatbot-ui

A beautiful, self-contained chatbot UI component for Next.js with Tailwind CSS. Perfect for customer support, AI assistants, and chat applications.

✨ All dependencies included! When you install this package, all required dependencies (mongodb, pg, chromadb, openai) are automatically installed - no need to install anything else!

⚡ Super Simple Usage (Just 2 Files!)

// app/page.tsx
'use client';
import { Chatbot } from 'nextjs-chatbot-ui';
export default function Home() {
  return <Chatbot config={{ backendUrl: '/api/chat' }} />;
}

// app/api/chat/route.ts
export async function POST(req: Request) {
  const { message } = await req.json();
  return Response.json({ message: `You said: ${message}` });
}

Done! See SIMPLE_SETUP.md for more examples.

Features

• 🎨 Modern, Sendbird-inspired UI design
• ⚙️ Fully configurable (labels, position, colors, backend URL)
• 📱 Responsive and mobile-friendly
• 🎯 TypeScript support
• 🚀 Easy to integrate
• 💬 Real-time messaging support
• 🎭 Customizable user and bot avatars
• ⏰ Optional timestamp display

Compatibility Requirements

This package requires:

• Next.js 13+ (with App Router or Pages Router support)
• React 18+
• TypeScript (optional, but recommended)
• Tailwind CSS 3+ (must be configured in your project)

Important Notes:

• The package exports TypeScript source files directly, which Next.js will compile automatically
• Make sure your tailwind.config.js includes the package path in the content array
• This package uses the 'use client' directive and requires client-side rendering
• Works with both App Router (app/ directory) and Pages Router (pages/ directory)

Installation

npm install nextjs-chatbot-ui

🚀 Super Simple Setup (Complete RAG Chatbot in 3 Steps!)

Everything works automatically! All dependencies are included - just run the setup script and add your .env file.

Step 1: Run Setup Script

npx nextjs-chatbot-ui-setup

This automatically creates all API routes needed for the chatbot and admin setup.

Step 2: Add Environment Variables

Create .env.local file:

OPENAI_API_KEY=your_openai_api_key_here
CHROMADB_URL=http://localhost:8000

Step 2.5: Start ChromaDB (Automatic)

The package includes a script to automatically check and start ChromaDB:

# Check and start ChromaDB automatically
npm run chromadb:check

# Or use Docker Compose
npm run chromadb:start

# Or manually with Docker
docker run -d --name chromadb -p 8000:8000 chromadb/chroma

What the script does:

• ✅ Checks if ChromaDB npm package is installed (installs if missing)
• ✅ Checks if Docker is installed and running
• ✅ Checks if ChromaDB container is running
• ✅ Starts ChromaDB container if not running
• ✅ Verifies ChromaDB is accessible

Alternative: Using Docker Compose

# Start ChromaDB
docker-compose up -d

# Stop ChromaDB
docker-compose stop

# Restart ChromaDB
docker-compose restart

Step 3: Use Components

// app/page.tsx
'use client';
import { Chatbot, AdminSetup } from 'nextjs-chatbot-ui';

export default function Home() {
  return (
    <div>
      <AdminSetup />
      <Chatbot config={{ backendUrl: '/api/chat' }} />
    </div>
  );
}

That's it! 🎉

• Use <AdminSetup /> to connect to your database and process embeddings
• Use <Chatbot /> to ask questions about your data
• Everything else is handled automatically!

Quick Start (Minimal Code)

Simplest Usage (Just 2 files!)

1. Add to your page:

// app/page.tsx
'use client';
import { Chatbot } from 'nextjs-chatbot-ui';

export default function Home() {
  return <Chatbot config={{ backendUrl: '/api/chat' }} />;
}

2. Create API endpoint:

// app/api/chat/route.ts
import { NextResponse } from 'next/server';

export async function POST(req: Request) {
  const { message } = await req.json();
  return NextResponse.json({ message: `You said: ${message}` });
}

Done! See SIMPLE_SETUP.md for more examples.

Usage

Basic Setup

Step 1: Configure Next.js - Add the package to your next.config.js:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['nextjs-chatbot-ui'],
  // ... your other config
}

module.exports = nextConfig

Step 2: Configure Tailwind CSS - Make sure your tailwind.config.js includes the component:

// tailwind.config.js
module.exports = {
  content: [
    './node_modules/nextjs-chatbot-ui/**/*.{js,ts,jsx,tsx}',
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  // ... rest of your config
}

Step 3: Import and use the component:

For App Router (app directory):

// app/page.tsx or app/any-page.tsx
'use client'; // Required for App Router

import { Chatbot } from 'nextjs-chatbot-ui';
import type { ChatbotConfig } from 'nextjs-chatbot-ui';

For Pages Router (pages directory):

// pages/index.js or pages/any-page.js
import { Chatbot } from 'nextjs-chatbot-ui';
import type { ChatbotConfig } from 'nextjs-chatbot-ui';

Step 4: Configure and use the component:

const config: ChatbotConfig = {
  backendUrl: 'https://your-backend-api.com/chat',
  labels: {
    title: 'Support Chat',
    placeholder: 'Type your message...',
    sendButton: 'Send',
    welcomeMessage: 'Hello! How can I help you?',
  },
  position: 'bottom-right',
  botInfo: {
    name: 'Support Bot',
    avatar: 'https://example.com/bot-avatar.png',
  },
  userInfo: {
    name: 'User',
    avatar: 'https://example.com/user-avatar.png',
  },
  primaryColor: '#0ea5e9',
  autoOpen: false,
  showTimestamp: true,
};

export default function Page() {
  return (
    <div>
      <h1>My Website</h1>
      <Chatbot config={config} />
    </div>
  );
}

Complete Example (App Router)

// app/page.tsx
'use client';

import { Chatbot } from 'nextjs-chatbot-ui';
import type { ChatbotConfig } from 'nextjs-chatbot-ui';

export default function Home() {
  const config: ChatbotConfig = {
    backendUrl: 'https://api.example.com/chat',
    labels: {
      title: 'Support Chat',
      placeholder: 'Type your message...',
      sendButton: 'Send',
      welcomeMessage: 'Hello! How can I help you today?',
    },
    position: 'bottom-right',
    botInfo: {
      name: 'Support Bot',
    },
    userInfo: {
      name: 'User',
    },
    primaryColor: '#6B46C1',
    autoOpen: false,
    showTimestamp: true,
  };

  return (
    <main>
      <h1>Welcome to My Site</h1>
      <Chatbot config={config} />
    </main>
  );
}

Complete Example (Pages Router)

// pages/index.js
import { Chatbot } from 'nextjs-chatbot-ui';

export default function Home() {
  const config = {
    backendUrl: 'https://api.example.com/chat',
    labels: {
      title: 'Support Chat',
      placeholder: 'Type your message...',
    },
    position: 'bottom-right',
  };

  return (
    <div>
      <h1>Welcome to My Site</h1>
      <Chatbot config={config} />
    </div>
  );
}

Configuration Options

ChatbotConfig Interface

interface ChatbotConfig {
  // Required
  backendUrl: string; // Your backend API endpoint for handling messages

  // Optional Labels
  labels?: {
    title?: string;              // Chat header title (default: "Chat Support")
    placeholder?: string;         // Input placeholder (default: "Type your message...")
    sendButton?: string;          // Send button text (default: "Send")
    typingIndicator?: string;     // Loading message (default: "Typing...")
    welcomeMessage?: string;      // Initial bot message (default: "Hello! How can I help you today?")
    errorMessage?: string;        // Error message (default: "Sorry, something went wrong. Please try again.")
  };

  // Position
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'; // Default: 'bottom-right'

  // User Information
  userInfo?: {
    name?: string;    // User name
    avatar?: string;  // User avatar URL
  };

  // Bot Information
  botInfo?: {
    name?: string;    // Bot name (default: uses title)
    avatar?: string;  // Bot avatar URL
  };

  // Styling
  primaryColor?: string;      // Primary color (hex code)
  backgroundColor?: string;   // Chat background color (hex code)

  // Behavior
  autoOpen?: boolean;         // Auto-open chat on load (default: false)
  showTimestamp?: boolean;    // Show message timestamps (default: false)
  showDateSeparator?: boolean; // Show date separators between messages (default: false)
  poweredByText?: string;     // Footer text (e.g., "Powered by sendbird")
}

Backend API Requirements

✅ Works with ANY backend! Express, FastAPI, Flask, Django, NestJS, Go, or any other framework.

Your backend just needs to implement one POST endpoint that accepts and returns JSON:

Request:

{
  "message": "User's message text",
  "userInfo": {
    "name": "User",
    "avatar": "https://example.com/avatar.png"
  }
}

Response (either format works):

{
  "message": "Bot's response text",
  "suggestedReplies": ["Option 1", "Option 2", "Option 3"]
}

or

{
  "response": "Bot's response text",
  "suggestions": ["Option 1", "Option 2", "Option 3"]
}

Note:

• The suggestedReplies or suggestions field is optional
• The component accepts either message or response in the response
• See BACKEND_INTEGRATION.md for examples with different backend frameworks (Express, FastAPI, Flask, Django, NestJS, Go, etc.)

Example Implementation

// pages/index.js or app/page.js
'use client';

import { Chatbot } from 'nextjs-chatbot-ui';
import type { ChatbotConfig } from 'nextjs-chatbot-ui';

export default function Home() {
  const chatbotConfig: ChatbotConfig = {
    backendUrl: 'https://api.example.com/chat',
    labels: {
      title: 'Customer Support',
      placeholder: 'Ask us anything...',
      sendButton: 'Send',
      welcomeMessage: 'Welcome! We\'re here to help.',
    },
    position: 'bottom-right',
    botInfo: {
      name: 'Support Assistant',
      avatar: '/bot-avatar.png',
    },
    userInfo: {
      name: 'Guest User',
    },
    primaryColor: '#6B46C1', // Purple like Sendbird
    autoOpen: false,
    showTimestamp: true,
    showDateSeparator: true,
    poweredByText: 'Powered by nextjs-chatbot-ui',
  };

  return (
    <div>
      <h1>My Website</h1>
      <Chatbot config={chatbotConfig} />
    </div>
  );
}

Tailwind CSS Setup

Make sure you have Tailwind CSS configured in your Next.js project. The component uses Tailwind classes, so ensure your tailwind.config.js includes the component:

// tailwind.config.js
module.exports = {
  content: [
    './node_modules/nextjs-chatbot-ui/**/*.{js,ts,jsx,tsx}',
    // ... your other paths
  ],
  // ... rest of your config
}

Development

To develop or modify this package:

# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build

Admin Setup Component

The package also includes an AdminSetup component for configuring database connections in your admin panel.

Usage

import { AdminSetup } from 'nextjs-chatbot-ui';
import type { DatabaseConfig, DatabaseConnection } from 'nextjs-chatbot-ui';

function AdminPanel() {
  const handleSave = (config: DatabaseConfig) => {
    // Save configuration to your backend
    console.log('Config:', config);
  };

  const handleTestConnection = async (connection: DatabaseConnection) => {
    // Test database connection
    const response = await fetch('/api/database/test', {
      method: 'POST',
      body: JSON.stringify(connection),
    });
    return response.ok;
  };

  const handleFetchColumns = async (connection: DatabaseConnection) => {
    // Fetch columns from database
    const response = await fetch('/api/database/columns', {
      method: 'POST',
      body: JSON.stringify(connection),
    });
    const data = await response.json();
    return data.columns || [];
  };

  return (
    <aside className="sidebar">
      <AdminSetup
        onSave={handleSave}
        onTestConnection={handleTestConnection}
        onFetchColumns={handleFetchColumns}
      />
    </aside>
  );
}

Features

• Database Selection: Choose between MongoDB and PostgreSQL
• Connection Configuration: Configure all necessary connection parameters
• Connection Testing: Test database connection before proceeding
• Column Selection: Select columns for:
  • Embedding processing
  • LLM processing
  • ChromaDB storage
• Embedding Settings: Configure embedding model, chunk size, and vector database
• Modal Interface: Clean, step-by-step modal interface
• Sidebar Integration: Ready to integrate into admin panel sidebars

Database Configuration

The component supports:

• MongoDB: Connection string or individual fields (host, port, database, SSL)
• PostgreSQL: Host, port, database, username, password, SSL

Embedding Settings Configuration

After selecting columns, you'll configure embedding processing options:

• Vector Database: Choose where to store embeddings (currently supports ChromaDB)
• Embedding Model: Select OpenAI embedding model:
  • text-embedding-3-small (default, cost-effective)
  • text-embedding-3-large (higher quality, more expensive)
• Chunk Size: Number of characters per chunk (0 to disable chunking)
  • Smaller chunks = more embeddings = better retrieval but higher cost
  • Recommended: 500-2000 characters
• Chunk Overlap: Characters to overlap between chunks
  • Helps preserve context across chunk boundaries
  • Recommended: 10-20% of chunk size

Example Settings:

• Chunk Size: 1000 characters
• Chunk Overlap: 100 characters
• Embedding Model: text-embedding-3-small

This will split long documents into 1000-character chunks with 100-character overlap, then generate embeddings for each chunk.

Backend API Requirements

Your backend should provide:

1. Test Connection Endpoint (POST /api/database/test)

   • Accepts DatabaseConnection object
   • Returns { success: boolean, message?: string }
   • Example response: { success: true } or { success: false, message: "Connection failed" }

2. Fetch Columns Endpoint (POST /api/database/columns)

   • Accepts DatabaseConnection object
   • Returns { columns: string[] } or { columnNames: string[] }
   • Example response: { columns: ["id", "title", "content", "description"] }

3. Save Configuration Endpoint (your implementation)

   • Accepts DatabaseConfig object
   • Saves configuration to your storage

Note: If you don't provide onTestConnection and onFetchColumns handlers, the component will automatically try to call /api/database/test and /api/database/columns endpoints. See example-api-routes.md for complete implementation examples.

Troubleshooting

Component not rendering or styles not working

1. Check Tailwind Configuration: Make sure nextjs-chatbot-ui is in your tailwind.config.js content array:

   content: [
     './node_modules/nextjs-chatbot-ui/**/*.{js,ts,jsx,tsx}',
     // ... other paths
   ]

2. Check Next.js Configuration: Ensure transpilePackages is set in next.config.js:

   transpilePackages: ['nextjs-chatbot-ui']

3. Restart Development Server: After configuration changes, restart your Next.js dev server.

TypeScript Errors

If you see TypeScript errors:

• Make sure you're using TypeScript 5+ (optional but recommended)
• The package includes type definitions, so TypeScript should work out of the box
• If using JavaScript, you can ignore type imports: import { Chatbot } from 'nextjs-chatbot-ui';

"Module not found" or Import Errors

1. Verify Installation: Run npm install nextjs-chatbot-ui again
2. Check Node Modules: Ensure the package exists in node_modules/nextjs-chatbot-ui
3. Clear Cache: Try deleting .next folder and node_modules, then reinstall

Component not appearing

• Make sure you're using 'use client' directive in App Router
• Check that the component is not hidden by CSS (z-index, overflow, etc.)
• Verify the position prop is set correctly

Backend API Issues

• Ensure your backend URL is correct and accessible
• Check CORS settings if making cross-origin requests
• Verify the API response format matches the expected structure (see Backend API Requirements)

Database Connection Not Working

If the database connection is not establishing:

1. Check if API endpoints exist: The component tries to call /api/database/test and /api/database/columns by default. Make sure these endpoints are implemented in your Next.js app.

2. Implement the endpoints: See example-api-routes.md for complete implementation examples for both App Router and Pages Router.

3. Provide custom handlers: You can also provide onTestConnection and onFetchColumns props to handle the connection logic yourself:

   <AdminSetup
     onTestConnection={async (connection) => {
       const response = await fetch('/your-api/test', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(connection),
       });
       const data = await response.json();
       return data.success === true;
     }}
     onFetchColumns={async (connection) => {
       const response = await fetch('/your-api/columns', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(connection),
       });
       const data = await response.json();
       return data.columns || [];
     }}
   />

4. Check browser console: Open browser DevTools console to see detailed error messages about connection failures.

5. Verify database credentials: Ensure your database host, port, username, password, and database name are correct.

RAG Chatbot Architecture

This package supports RAG (Retrieval-Augmented Generation) chatbot architecture for answering questions about your database.

Architecture Flow

React UI → Express API → MongoDB + ChromaDB → OpenAI

1. Setup Phase: Use AdminSetup component to connect to database, select collections/columns, and process embeddings
2. Query Phase: Use Chatbot component to ask questions, which are answered using vector search and LLM generation

Quick Start with RAG

1. Set up backend (run the setup script):

   • Run npx nextjs-chatbot-ui-setup to automatically create all API routes
   • This creates Next.js API routes with MongoDB, ChromaDB, and OpenAI integration
   • Endpoints: /api/chat, /api/database/test, /api/database/collections, /api/database/columns, /api/database/process-embeddings

2. Configure chatbot:

   const config: ChatbotConfig = {
     backendUrl: '/api/search', // RAG search endpoint
     labels: {
       title: 'RAG Chatbot',
       placeholder: 'Ask me anything about your data...',
     },
   };

3. Use AdminSetup to:

   • Connect to your database
   • Select collections and columns
   • Configure embedding settings (model, chunk size, vector database)
   • Process embeddings (fetches data → chunks text → converts to embeddings → stores in ChromaDB)

4. Query your data using the Chatbot component

For complete RAG architecture documentation, see RAG_ARCHITECTURE.md.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.