Overview

EasyRAG provides production-ready React components that make it easy to add RAG capabilities to your application. These components handle authentication, API calls, error handling, and provide beautiful UIs out of the box.

Available Components

FileUpload

Drag-and-drop file upload with progress tracking, metadata support, and custom chunking options.

SearchBox

Semantic search interface with customizable result display, filtering, and scoring.

ChatBox

AI-powered chat interface with streaming responses, message history, and auto-scroll.

FileViewer

Browse, preview, and manage uploaded files with metadata display and deletion.

Why Use Our Components?

🚀 Zero Configuration

Drop components into your React app and they work immediately. No complex setup required.

tsx
import { FileUpload } from '@easyrag/react-components';

<FileUpload token={token} datasetId="my-dataset" />

🎨 Fully Customizable

Three built-in themes (default, minimal, custom) and extensive props for styling, labels, and behavior.

tsx
<SearchBox
  token={token}
  datasetId="my-dataset"
  theme="minimal"
  showScore={true}
  customStyles={{
    input: 'my-custom-input',
    button: 'my-custom-button'
  }}
/>

🔒 Secure by Default

Components support frontend token authentication, keeping your API keys safe on the backend.

tsx
// Backend generates short-lived token
const token = await generateFrontendToken({
  customerId: user.id,
  datasetId: 'dataset-id',
  ttlSeconds: 3600
});

// Frontend uses token securely
<ChatBox token={token} datasetId="dataset-id" />

📱 Production Ready

Built with TypeScript, includes error handling, loading states, and accessibility features.

🎯 TypeScript Support

Full type definitions included for excellent autocomplete and type safety.

typescript
import type { 
  FileUploadProps, 
  SearchBoxProps, 
  ChatBoxProps 
} from '@easyrag/react-components';

Installation

bash
npm install @easyrag/react-components

Quick Example

Here's a complete RAG application in just a few lines:

tsx
import { FileUpload, SearchBox, ChatBox } from '@easyrag/react-components';

function MyRAGApp() {
  const [token, setToken] = useState('');

  // Get token from your backend
  useEffect(() => {
    fetch('/api/tokens/create', { method: 'POST' })
      .then(r => r.json())
      .then(data => setToken(data.token));
  }, []);

  if (!token) return <div>Loading...</div>;

  return (
    <div className="space-y-8">
      {/* Upload documents */}
      <FileUpload 
        token={token} 
        datasetId="my-dataset"
        onUploadComplete={() => console.log('Upload complete!')}
      />

      {/* Search documents */}
      <SearchBox 
        token={token} 
        datasetId="my-dataset"
        showScore={true}
      />

      {/* Chat with documents */}
      <ChatBox 
        token={token} 
        datasetId="my-dataset"
        stream={true}
      />
    </div>
  );
}

Component Features

FileUpload

• ✅ Drag & drop interface
• ✅ Multi-file support (configurable)
• ✅ Progress indicators
• ✅ File type restrictions
• ✅ Size limits
• ✅ Metadata builder function
• ✅ Custom chunking options
• ✅ Error handling

SearchBox

• ✅ Semantic search interface
• ✅ Real-time results
• ✅ Relevance score display
• ✅ Metadata filtering
• ✅ Custom result rendering
• ✅ Empty state handling
• ✅ Loading states

ChatBox

• ✅ Streaming responses
• ✅ Non-streaming mode
• ✅ Message history
• ✅ Auto-scroll to latest
• ✅ User/Assistant styling
• ✅ Initial messages support
• ✅ Error recovery

FileViewer

• ✅ File list with metadata
• ✅ File selection and preview
• ✅ Permanent URLs
• ✅ Delete functionality
• ✅ Transcription display (for media)
• ✅ Custom filter support

Authentication

All components support two authentication modes:

Frontend Tokens (Recommended)

Generate a short‑lived token in your backend, then pass it to the React components.

Option 1 – Node.js backend using the HTTP API

ts
import express from "express";

const router = express.Router();

router.post("/api/easyrag-token", authenticateUser, async (req, res) => {
  const { datasetId } = req.body;

  if (!datasetId) {
    return res.status(400).json({ error: "datasetId is required" });
  }

  const response = await fetch("https://api.easyrag.com/v1/tokens/create", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.EASY_RAG_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ datasetId, ttlSeconds: 3600 }),
  });

  const data = await response.json();
  return res.status(response.ok ? 200 : response.status).json(data);
});

Option 2 – Node.js backend using the SDK

ts
import { EasyRAG } from "@easyrag/sdk";

const client = new EasyRAG({
  apiKey: process.env.EASY_RAG_KEY!,
});

app.post("/api/easyrag-token", authenticateUser, async (req, res) => {
  const { datasetId } = req.body;

  if (!datasetId) {
    return res.status(400).json({ error: "datasetId is required" });
  }

  const result = await client.createToken(datasetId, { ttlSeconds: 3600 });
  res.json(result);
});

Option 3 – Next.js route example

ts
import { NextResponse } from "next/server";
import { EasyRAG } from "@easyrag/sdk";

export const runtime = "nodejs"; // important if the SDK relies on Node APIs

const client = new EasyRAG({
  apiKey: process.env.EASY_RAG_KEY,
});

export async function POST(request: Request) {
  try {
    const { datasetId } = await request.json();

    if (!datasetId) {
      return NextResponse.json(
        { error: "datasetId is required" },
        { status: 400 }
      );
    }

    const result = await client.createToken(datasetId, { ttlSeconds: 3600 });

    return NextResponse.json(result, { status: 200 });
  } catch (err) {
    console.error("Token proxy error", err);
    return NextResponse.json(
      { error: "Token proxy error" },
      { status: 500 }
    );
  }
}

Frontend fetch example (React)

tsx
import { useEffect, useState } from "react";
import { FileUpload } from "@easyrag/react-components";

function MyRAGApp() {
  const [token, setToken] = useState<string | null>(null);

  useEffect(() => {
    async function fetchToken() {
      const res = await fetch("/api/easyrag-token", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ datasetId: "my-dataset" }),
      });

      const data = await res.json();
      setToken(data.token);
    }

    fetchToken();
  }, []);

  if (!token) return <div>Loading...</div>;

  return <FileUpload token={token} datasetId="my-dataset" />;
}

API Keys (Internal Tools Only)

For internal tools or development:

tsx
<FileUpload 
  token={process.env.EASYRAG_API_KEY}
  datasetId="my-dataset"
/>

⚠️ Never expose API keys in production frontends!

Theming

Default Theme

Clean, modern design with EasyRAG branding:

tsx
<SearchBox token={token} datasetId="dataset" theme="default" />

Minimal Theme

Lightweight styling, easy to integrate:

tsx
<SearchBox token={token} datasetId="dataset" theme="minimal" />

Custom Theme

Full control with your own styles:

tsx
<SearchBox
  token={token}
  datasetId="dataset"
  theme="custom"
  customStyles={{
    container: 'my-container',
    input: 'my-input',
    button: 'my-button',
    resultCard: 'my-result-card'
  }}
/>

Branding

Components include an optional "Powered by EasyRAG" watermark:

tsx
// Show watermark (default)
<ChatBox 
  token={token} 
  datasetId="dataset"
  showPoweredBy={true}
/>

// Hide watermark
<ChatBox 
  token={token} 
  datasetId="dataset"
  showPoweredBy={false}
/>

// Custom URL
<ChatBox 
  token={token} 
  datasetId="dataset"
  poweredByUrl="https://yourcompany.com"
/>

Multi-Tenant Support

Components work seamlessly with multi-tenant applications:

tsx
// Upload with tenant metadata
<FileUpload
  token={token}
  datasetId="shared-dataset"
  metadataBuilder={(file, index) => ({
    userId: currentUser.id,
    department: currentUser.department,
    uploadedAt: new Date().toISOString()
  })}
/>

// Search with tenant filtering
<SearchBox
  token={token}
  datasetId="shared-dataset"
  filters={[
    { key: 'userId', match: { value: currentUser.id } }
  ]}
/>

Use Cases

Customer Support Portal

tsx
<ChatBox
  token={token}
  datasetId="support-kb"
  initialMessages={[
    { 
      id: 1, 
      role: 'assistant', 
      content: 'Hi! How can I help you today?' 
    }
  ]}
  filters={[
    { key: 'category', match: { value: 'billing' } }
  ]}
/>

Internal Documentation Search

tsx
<SearchBox
  token={token}
  datasetId="company-docs"
  filters={[
    { key: 'department', match: { value: user.department } },
    { key: 'confidential', match: { value: false } }
  ]}
  showMetadata={true}
/>

Document Upload Portal

tsx
<FileUpload
  token={token}
  datasetId="user-documents"
  maxFiles={5}
  maxFileSize={10 * 1024 * 1024} // 10MB
  accept={{ 'application/pdf': ['.pdf'] }}
  metadataBuilder={(file) => ({
    originalName: file.name,
    uploadedBy: currentUser.email
  })}
/>

File Management

tsx
<FileViewer
  token={token}
  datasetId="my-dataset"
  onFileDelete={(fileId) => {
    console.log('File deleted:', fileId);
    refetchFiles();
  }}
  onFileSelect={(file) => {
    console.log('Selected file:', file);
  }}
/>

Browser Support

• Chrome/Edge: Latest 2 versions
• Firefox: Latest 2 versions
• Safari: Latest 2 versions

Next Steps

• FileUpload Component - Detailed documentation
• SearchBox Component - Detailed documentation
• ChatBox Component - Detailed documentation
• FileViewer Component - Detailed documentation
• Example Projects - Full working examples

Need Help?

• 📧 Email: support@easyrag.com
• 💬 Discord: Join our community
• 🐛 Issues: GitHub