A lightweight, standalone bug reporting library for React applications.
npm install bughubA lightweight, standalone bug reporting library for React applications. Capture errors, screenshots, system info, and AI insights effortlessly.
- 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.
``bash`
npm install bughub
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/headersBugHub.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 (
{/ Your App Content /}
);
};
`$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 (
{/ Your custom button /}
{/ Your App Content /}
);
};
`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 /}
`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 passwordRecipients
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_dotenvload_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_USERBug 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.MIT