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 📦

``bash
npm install bughub
`

Quick Start 🚀

$3

Run the interactive setup wizard to configure BugHub automatically:

`bash
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:

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

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

function App() {
return (



);
}
`

$3

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

`javascript
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:

`javascript
const App = () => {
return (



);
};
`

$3

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:

`javascript

`

2. Custom Color:

`javascript
position="bottom-right"
color="#ef4444" // Red
/>
`

3. Add Label:

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

4. Custom Icon:

`javascript
position="bottom-right"
icon={}
color="#f59e0b" // Orange
/>
`

5. Full Customization:

`javascript
position="top-right"
color="#8b5cf6" // Purple
label="Help"
icon={}
style={{ fontSize: "14px" }}
/>
`

$3

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

`javascript
import { BugHub, BugHubProvider } from "bughub";

const App = () => {
return (



);
};
`

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

$3

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

1. Initialize BugHub in your root component:

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

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

const App = () => {
return (

{/ 🚀 Add this for automatic path tracking in Expo Router /}



{/ Your App Content /}
BugHub.open()} />

);
};
`

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)

$3

You have 3 options to configure the modal language:

#### Option 1: Explicit Configuration (Recommended)

Set the language parameter in BugHub.init():

`javascript
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:

`html




`

#### Option 3: Browser Default

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

$3

BugHub follows this priority order:

1. language in BugHub.init() (highest priority)
2. attribute
3. Default to English (fallback)

$3

`javascript
// 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;
`

$3

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.

$3

| 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). |

$3

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

`python
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='system@yourdomain.com',
to=['support@yourdomain.com'],
)
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)
`

$3

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

`javascript
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);
`

$3

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:

`env


SMTP Configuration

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

Recipients

RECIPIENT_EMAIL=support@yourdomain.com # 📥 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:

`python
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', 'support@yourdomain.com'), # 📥 Recipient email
# Add more recipients if needed:
# 'dev-team@yourdomain.com',
# 'admin@yourdomain.com',
]
`

Then update your view to use these settings:

`python
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