trapshot-widget
v1.0.4
Published
A TypeScript widget for bug reporting with screenshot capture, console logging, and server integration
Maintainers
Readme
TrapShot Widget
A TypeScript widget for bug reporting with screenshot capture, console logging, and server integration. This widget can be easily dropped into any web project to provide users with a seamless bug reporting experience.
Features
- 🐛 Easy Bug Reporting - Floating widget with intuitive form
- 📸 Screenshot Capture - Automatic screenshot capture using html2canvas
- 📝 Console Log Collection - Captures and includes console logs
- 🎨 Customizable Themes - Light and dark themes
- 📱 Mobile Responsive - Works on all device sizes
- 🔧 TypeScript Support - Full TypeScript definitions included
- 🌐 Server Integration - Ready for backend integration
- 📦 Multiple Build Formats - UMD for CDN, ES modules for bundlers
- ⚡ Zero Dependencies - Only requires html2canvas for screenshots
Quick Start
CDN Usage (Standalone)
<!-- Include the widget -->
<script src="https://your-cdn.com/trapshot.js"></script>
<!-- Initialize -->
<script>
const trapShot = new TrapShot({
position: 'bottom-right',
theme: 'light',
autoCapture: true,
showConsoleToggle: true
});
</script>NPM Installation
npm install trapshot-widgetES Module Usage
import { TrapShot, type TrapShotOptions } from 'trapshot-widget';
const options: TrapShotOptions = {
position: 'bottom-right',
theme: 'light',
autoCapture: true,
showConsoleToggle: true,
customLabels: ['frontend', 'production'],
serverUrl: 'https://your-api.com/bugs'
};
const trapShot = new TrapShot(options);Configuration Options
interface TrapShotOptions {
position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
theme?: 'light' | 'dark';
autoCapture?: boolean; // Auto-capture screenshot when opened
showConsoleToggle?: boolean; // Show console logs section
customLabels?: string[]; // Custom labels to add to reports
serverUrl?: string | null; // URL for server submission
}Default Values
{
position: 'bottom-right',
theme: 'light',
autoCapture: true,
showConsoleToggle: true,
customLabels: [],
serverUrl: null
}API Reference
Constructor
const trapShot = new TrapShot(options?: TrapShotOptions);Methods
// Initialize the widget (called automatically)
trapShot.init(): void
// Destroy the widget and cleanup
trapShot.destroy(): void
// Event handlers (override these)
trapShot.onBugReported(bugReport: BugReport): void
trapShot.onReportSubmitted(result: ServerResponse): voidBug Report Object
When a bug is reported, the following object is created:
interface BugReport {
title: string; // "[SEVERITY] Bug title"
description: string; // Description with category/severity
consoleLogs: string[]; // Array of console log entries
userAgent: string; // Browser user agent
url: string; // Current page URL
timestamp: Date; // When the report was created
screenshot?: string; // Base64 encoded screenshot (if enabled)
additionalInfo: {
customLabels: string[]; // Your custom labels
};
}Server Integration
The widget can POST bug reports to your server endpoint:
const trapShot = new TrapShot({
serverUrl: 'https://your-api.com/bugs'
});
// Handle successful submission
trapShot.onReportSubmitted = function(result) {
console.log('Bug submitted:', result);
// Show success message to user
};Expected Server Response
interface ServerResponse {
success: boolean;
issueUrl?: string; // Link to created issue (e.g., GitHub)
message?: string; // Success/error message
}Example Server Handler (Node.js/Express)
app.post('/api/bugs', async (req, res) => {
try {
const bugReport = req.body;
// Process the bug report
// - Save to database
// - Create GitHub issue
// - Send notifications
const issueUrl = await createGitHubIssue(bugReport);
res.json({
success: true,
issueUrl: issueUrl,
message: 'Bug report submitted successfully'
});
} catch (error) {
res.status(500).json({
success: false,
message: error.message
});
}
});Development
Prerequisites
- Node.js 16+
- npm or yarn
Setup
# Clone the repository
git clone <repository-url>
cd trapshot-widget
# Install dependencies
npm install
# Build the project
npm run build
# Start development server
npm run devBuild Scripts
npm run build # Build both library and widget
npm run build:lib # Build TypeScript library
npm run build:widget # Build standalone widget
npm run dev # Start development server
npm run clean # Clean dist folderProject Structure
src/
├── types/
│ └── index.ts # TypeScript type definitions
├── TrapShot.ts # Main widget class
├── index.ts # Library entry point
├── widget.ts # Standalone widget entry point
└── styles.css # Widget styles
dist/
├── trapshot.js # Standalone widget (UMD)
├── trapshot.css # Extracted CSS
├── index.js # ES module version
├── index.d.ts # TypeScript definitions
└── demo.html # Demo page
examples/
└── demo.html # Example usageBrowser Support
- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+
Dependencies
- html2canvas - For screenshot capture
- Development only: TypeScript, Webpack, and build tools
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
MIT License - see LICENSE file for details
Changelog
v1.0.0
- Initial TypeScript release
- Improved folder structure
- Added build system with Webpack
- Full TypeScript support
- UMD and ES module builds
- Enhanced documentation
Support
For issues and questions:
- Create an issue on GitHub
- Check the examples folder for usage patterns
- Review the TypeScript definitions for API details
