BugHub 🐞

A lightweight, standalone bug reporting library for React applications. Capture errors, screenshots, system info, and AI insights effortlessly.

Features ✨

• Automatic Screenshot Capture: Uses html2canvas to capture the current screen state.
• System Info Detection: Automatically detects OS, Browser, and Device Type (Mobile/Tablet/Desktop).
• Console & Network Logging: Captures recent console logs and network errors.
• AI Analysis 🤖: innovative feature to analyze error logs using AI (Gemini) directly from the frontend or via backend.
• Pre-designed Email Attributes: Sends a beautifully styled HTML email template to your backend.
• Framework Agnostic: Works with any React application.
• Multi-language Support: English, Arabic, and Turkish.

Installation 📦

npm install bughub

Quick Start 🚀

Option 1: Automatic Setup (Recommended) ⚡

Run the interactive setup wizard to configure BugHub automatically:

npx bughub init

This will:

• Create a bughub.config.js file with your configuration
• Optionally generate a backend example (Node.js or Django)
• Guide you through AI provider selection (Gemini, OpenAI, or None)
• Set up the complete integration automatically

After running the wizard, import and use the generated configuration:

import { BugHub, BugHubProvider, BugHubFloatingButton } from "bughub";
import { bughubConfig } from "./bughub.config.js";

// Initialize BugHub with the generated config
BugHub.init(bughubConfig);

function App() {
  return (
    <div>
      <BugHubProvider />
      <BugHubFloatingButton position="bottom-right" />
      {/* Your App Content */}
    </div>
  );
}

Option 2: Manual Setup 🔧

1. Initialize BugHub in your main app file (e.g., App.js or index.js):

import { BugHub, BugHubProvider, BugHubFloatingButton } from "bughub";
import axios from "axios"; // Optional, for sharing auth/headers

BugHub.init({
  // 1. Endpoint Configuration
  // If not provided, it defaults to: axios.defaults.baseURL + '/api/bughub/report'
  endpoint: "https://api.yourdomain.com/report-problem",

  // 2. Axios Instance (Recommended)
  // Shared axios instance allows BugHub to inherit your auth headers/tokens automatically.
  axios: axios,

  // 3. User Info (Optional)
  // Can also be detected automatically from axios headers if configured.
  user: {
    username: "John Doe",
    id: 123,
    role: "Admin",
  },

  // 4. Language (Optional) 🌐
  // Supported: 'en' (English), 'ar' (Arabic), 'tr' (Turkish)
  // If not set, it will auto-detect from the browser's language
  language: "en",

  // 5. AI Analysis (Optional) 🤖
  // 'gemini' | 'openai' | 'none'
  ai_provider: "gemini",

  // For development only! In production, handle this server-side.
  geminiApiKey: "YOUR_GEMINI_API_KEY_DEV_ONLY",
});

2. Add the Provider & Button:

const App = () => {
  return (
    <div>
      <BugHubProvider />
      <BugHubFloatingButton position="bottom-right" />
      {/* Your App Content */}
    </div>
  );
};

Customizing the Floating Button 🎨

The BugHubFloatingButton component supports several customization options:

Available Props:

| Prop | Type | Default | Description | | ---------- | ----------- | ---------------- | ------------------------------------------------------------------------------- | | position | string | "bottom-right" | Button position: "bottom-right", "bottom-left", "top-right", "top-left" | | color | string | "#2563eb" | Background color (any CSS color) | | icon | ReactNode | Bug icon | Custom icon component | | label | string | undefined | Text label next to the icon | | style | object | {} | Additional custom styles |

Examples:

1. Change Position:

<BugHubFloatingButton position="bottom-left" />

2. Custom Color:

<BugHubFloatingButton
  position="bottom-right"
  color="#ef4444" // Red
/>

3. Add Label:

<BugHubFloatingButton
  position="bottom-right"
  label="Report Bug"
  color="#10b981" // Green
/>

4. Custom Icon:

<BugHubFloatingButton
  position="bottom-right"
  icon={<i className="bi bi-exclamation-triangle-fill"></i>}
  color="#f59e0b" // Orange
/>

5. Full Customization:

<BugHubFloatingButton
  position="top-right"
  color="#8b5cf6" // Purple
  label="Help"
  icon={<i className="bi bi-question-circle-fill"></i>}
  style={{ fontSize: "14px" }}
/>

Option 3: Custom Button Integration 🎨

If you prefer to use your own custom button instead of the floating button:

import { BugHub, BugHubProvider } from "bughub";

const App = () => {
  return (
    <div>
      <BugHubProvider />

      {/* Your custom button */}
      <button className="your-custom-class" onClick={() => BugHub.open()}>
        <i className="bi bi-bug-fill"></i>
        Report a Bug
      </button>

      {/* Your App Content */}
    </div>
  );
};

Note: You can use both the floating button and custom buttons together. The BugHub.open() method can be called from anywhere in your application.

Option 4: React Native Setup 📱

BugHub now supports React Native with a beautiful, premium modal designed for mobile.

1. Initialize BugHub in your root component:

import { BugHub, BugHubProvider, BugHubNavigation } from "bughub";

BugHub.init({
  endpoint: "https://api.yourdomain.com/report",
  user: { username: "MobileUser" },
});

const App = () => {
  return (
    <View style={{ flex: 1 }}>
      {/* 🚀 Add this for automatic path tracking in Expo Router */}
      <BugHubNavigation />

      <BugHubProvider />
      {/* Your App Content */}
      <Button title="Report Bug" onPress={() => BugHub.open()} />
    </View>
  );
};

Note: If you are not using Expo Router, you can set the path manually whenever the screen changes: BugHub.setPath("/your/screen/name");.

Note: For React Native, the modal is automatically optimized for mobile screens with a premium dark-themed error log viewer.

Language Configuration 🌐

BugHub supports 4 languages for the bug report modal:

• 🇬🇧 English (en)
• 🇸🇦 Arabic (ar) - with RTL support
• 🇹🇷 Turkish (tr)
• 🇹🇼 Traditional Chinese (ch)

How to Set the Language

You have 3 options to configure the modal language:

Option 1: Explicit Configuration (Recommended)

Set the language parameter in BugHub.init():

BugHub.init({
  endpoint: "https://api.yourdomain.com/report",
  language: "ar", // Force Arabic
  // ... other config
});

Option 2: HTML Lang Attribute (Auto-detection)

If you don't specify a language, BugHub will automatically detect it from your HTML:

<!-- In your index.html -->
<html lang="ar">
  <!-- BugHub will automatically use Arabic -->
</html>

Option 3: Browser Default

If neither option 1 nor 2 is set, BugHub defaults to English (en).

Language Priority

BugHub follows this priority order:

1. language in BugHub.init() (highest priority)
2. <html lang="..."> attribute
3. Default to English (fallback)

Example: Multi-language Application

// Detect user's preferred language from your app
const userLanguage = localStorage.getItem("app_language") || "en";

BugHub.init({
  endpoint: "https://api.yourdomain.com/report",
  language: userLanguage, // Dynamic language
  user: { username: "User123" },
});

// Update HTML lang attribute for consistency
document.documentElement.lang = userLanguage;

RTL Support

Arabic language automatically enables Right-to-Left (RTL) layout for the modal, including:

• ✅ Reversed text direction
• ✅ Mirrored UI elements
• ✅ Proper icon positioning
• ✅ RTL-aware spacing

Backend Integration 🛠️

BugHub sends a multipart/form-data POST request to your endpoint.

Payload Structure

| Key | Description | | ------------------ | ------------------------------------------------------------------ | | explian_problem | User's description of the issue. | | problem_path | URL where the issue occurred. | | email_html | NEW! Ready-to-send HTML email template. | | system_info | JSON array: ["OS: macOS", "Browser: Chrome", "Device: Desktop"]. | | error_details | Formatted logs + AI Analysis text. | | pictures_problem | Array of attached files (screenshots). |

Django View Example

Since BugHub sends a pre-styled HTML email in email_html, you just need to forward it!

from django.core.mail import EmailMessage
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt

@csrf_exempt
def report_problem(request):
    if request.method == 'POST':
        description = request.POST.get('explian_problem', 'No description')
        email_html = request.POST.get('email_html', '') # 🌟 Ready-to-use HTML
        files = request.FILES.getlist('pictures_problem')

        email = EmailMessage(
            subject=f"Bug Report: {description[:50]}...",
            body=email_html, # Just use the provided HTML
            from_email='[email protected]',
            to=['[email protected]'],
        )
        email.content_subtype = "html" # Important!

        for f in files:
            email.attach(f.name, f.read(), f.content_type)

        email.send()
        return JsonResponse({'success': True})

    return JsonResponse({'error': 'Invalid method'}, status=405)

Node.js / Express Example

To handle multipart/form-data and send emails in Node.js, you can use multer and nodemailer:

const express = require("express");
const multer = require("multer");
const nodemailer = require("nodemailer");
const upload = multer();
const app = express();

app.post("/report-bug", upload.array("pictures_problem"), async (req, res) => {
  const { explian_problem, email_html } = req.body;
  const files = req.files;

  const transporter = nodemailer.createTransport({
    host: process.env.SMTP_HOST,
    port: process.env.SMTP_PORT,
    auth: {
      user: process.env.SMTP_USER,
      pass: process.env.SMTP_PASS,
    },
  });

  const mailOptions = {
    from: process.env.SMTP_USER,
    to: process.env.RECIPIENT_EMAIL,
    subject: `Bug Report: ${explian_problem.substring(0, 50)}`,
    html: email_html, // 🌟 Use the pre-styled HTML template
    attachments: files.map((file) => ({
      filename: file.originalname,
      content: file.buffer,
    })),
  };

  try {
    await transporter.sendMail(mailOptions);
    res.status(200).json({ success: true });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000);

Email Configuration 📧

To configure the sender and recipient emails, use environment variables in your backend:

For Node.js Backend:

Create a .env file in your backend directory:

# SMTP Configuration
SMTP_HOST=smtp.gmail.com          # Your SMTP server
SMTP_PORT=587                      # SMTP port (587 for TLS, 465 for SSL)
[email protected]     # 📤 Sender email (FROM)
SMTP_PASS=your_app_password        # Email password or app-specific password

# Recipients
[email protected]  # 📥 Recipient email (TO)

# Optional: AI Configuration
GEMINI_API_KEY=your_gemini_api_key_here

Note for Gmail users: You need to use an App Password instead of your regular password.

For Django Backend:

Add to your settings.py:

import os
from dotenv import load_dotenv

load_dotenv()

# Email Configuration
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = os.getenv('SMTP_HOST', 'smtp.gmail.com')
EMAIL_PORT = int(os.getenv('SMTP_PORT', 587))
EMAIL_USE_TLS = True
EMAIL_HOST_USER = os.getenv('SMTP_USER')  # 📤 Sender email
EMAIL_HOST_PASSWORD = os.getenv('SMTP_PASS')
DEFAULT_FROM_EMAIL = EMAIL_HOST_USER

# Bug Report Recipients
BUG_REPORT_RECIPIENTS = [
    os.getenv('RECIPIENT_EMAIL', '[email protected]'),  # 📥 Recipient email
    # Add more recipients if needed:
    # '[email protected]',
    # '[email protected]',
]

Then update your view to use these settings:

from django.conf import settings

@csrf_exempt
def report_problem(request):
    if request.method == 'POST':
        # ... (previous code)

        email = EmailMessage(
            subject=f"Bug Report: {description[:50]}...",
            body=email_html,
            from_email=settings.DEFAULT_FROM_EMAIL,  # 📤 From .env
            to=settings.BUG_REPORT_RECIPIENTS,        # 📥 From .env
        )
        email.content_subtype = "html"

        # ... (rest of the code)

Common SMTP Providers:

| Provider | SMTP Host | Port | Notes | | --------------------- | --------------------- | ---- | -------------------------------------------------------------------------- | | Gmail | smtp.gmail.com | 587 | Requires App Password | | Outlook/Office365 | smtp.office365.com | 587 | Use your Microsoft account | | Yahoo | smtp.mail.yahoo.com | 587 | Requires App Password | | SendGrid | smtp.sendgrid.net | 587 | Use API key as password | | Mailgun | smtp.mailgun.org | 587 | Use SMTP credentials from dashboard |

AI Analysis Configuration 🧠

You have two ways to enable AI analysis for error logs:

1. Frontend-side (Dev/Testing): Pass geminiApiKey in BugHub.init(). The library will call Google Gemini API directly. Note: Not recommended for production as it exposes your API key.

2. Backend-side (Production): If geminiApiKey is missing, BugHub sends the logs to your backend endpoint (e.g., /analyze). Your backend should call the AI service and return the result.

License 📄

MIT